Ad Library API for multi-platform ad research

Retrieve and organize the ad research saved in your Swipekit workspace from dashboards, automations, and internal tools.

One workspace, structured access

Connect your saved ad research to the rest of your workflow

Swipekit's API gives your team programmatic access to records and available assets already stored in its workspace. It is an independent Swipekit service rather than an official API from Meta, TikTok, or another ad platform.

Supported sources

Filter saved research by networks documented in the current specification, including Facebook, Instagram, and TikTok. Returned data depends on what is available in your workspace.

Built for working teams

Use the API for agency reporting, internal creative dashboards, research pipelines, and repeatable automations built around your team's saved ads.

Workspace authentication

Generate an API key in workspace settings, then send it as a Bearer token. Keep the key on your server and out of public client-side code.

Usage and rate limits

API access requires a trial or active paid workspace. Requests may be delayed above 120 per minute, with a hard limit of 200 requests per minute.

Quick start

Make your first request

This example returns up to two saved Facebook records. The response includes the matching records and pagination details described in the live reference below.

curl "https://api.swipekit.app/api/v1/library?take=2&networks=facebook" \
  -H "Authorization: Bearer <SWIPEKIT_API_KEY>"
{
	"data": [
		{
			"id": "ad-id",
			"block": { "type": "facebook", "networks": ["facebook"] }
		}
	],
	"pagination": { "page": 1, "pageSize": 2, "count": 2 }
}

REST API or MCP?

Use this REST API for structured HTTP integrations. Use Swipekit MCP when you want an AI assistant to work with your workspace through conversational tools.

Swipekit API

Welcome to the Swipekit API. If you're just getting started, you're in the right place. Quick start: 1. Generate an API key in Swipekit workspace settings. 2. Add the header: Authorization: Bearer sk_xxxxxxxxxxxxxxxx 3. Call /api/v1 endpoints. Response shape: public endpoints return an object with a data field, and data is an array. Paginated endpoints also return a pagination object. Workspace access: use the API with trial or active paid workspaces. Deactivated workspaces are blocked. Rate limits: up to 120 requests/min before delay, and a hard cap at 200 requests/min.

Base URL: https://api.swipekit.app

Asset base URL: https://file.swipekit.app

Prefer using Swipekit from your chat app? You can also use our MCP server as an optional interface. Set up Swipekit MCP.

GET /api/v1/ad/{id}

Get one ad by id

Get one ad by id

Fetch a specific saved ad by id from your workspace. Authentication: - Header: `Authorization: Bearer sk_<16_lowercase_alnum>` Workspace requirements: - Use this API with trial or active paid workspaces. - Deactivated workspaces receive `403`. Rate limits: - Up to 120 requests/min before delay. - Hard cap at 200 requests/min (`429`).

Parameters

Name In Required Type Description
id path Yes string Ad id.

Request Body

No request body.

Responses

Status Description Content types Schema
200 Ad returned successfully. application/json object(1 fields)
401 Missing or invalid API key. application/json object(1 fields)
403 Workspace is deactivated. application/json object(1 fields)
429 Rate limit exceeded. application/json object(1 fields)
500 Internal server error. application/json object(1 fields)
Response 200 (application/json)
{
  "data": [
    {
      "id": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
      "blockId": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
      "userId": 91,
      "createdAt": "2026-03-10T03:42:15.220Z",
      "updatedAt": "2026-03-10T03:42:15.220Z",
      "block": {
        "id": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
        "title": "Coastal Bay Retreat",
        "type": "facebook",
        "assetType": "image",
        "status": "INACTIVE",
        "metaId": "590012345678900",
        "assets": [
          {
            "type": "image",
            "ratio": 0.6665,
            "assetPath": "fb-590012345678900-a1b2c3d4-1.jpeg"
          }
        ],
        "meta": {
          "cta": "MESSAGE_PAGE",
          "isEuAd": false,
          "displayFormat": "image"
        },
        "createdAt": "2026-03-10T03:42:15.211Z",
        "brand": {
          "id": 30110,
          "name": "Coastal Bay Retreat",
          "slug": "coastal-bay-retreat",
          "logo": "coastal-bay-retreat-avatar.jpeg"
        }
      }
    }
  ]
}
Response 401 (application/json)
{
  "error": "Missing Bearer token"
}
Response 403 (application/json)
{
  "error": "Workspace is deactivated. Please select a plan to use the API."
}
Response 429 (application/json)
{
  "error": "Rate limit exceeded"
}
Response 500 (application/json)
{
  "error": "Internal server error"
}
GET /api/v1/ai-generation

List AI generations

List AI generations

Get AI generations created in your workspace. Authentication: - Header: `Authorization: Bearer sk_<16_lowercase_alnum>` Workspace requirements: - Use this API with trial or active paid workspaces. - Deactivated workspaces receive `403`. Rate limits: - Up to 120 requests/min before delay. - Hard cap at 200 requests/min (`429`).

Parameters

Name In Required Type Description
page query No integer Page number (default 1). Page size is fixed at 100.

Request Body

No request body.

Responses

Status Description Content types Schema
200 AI generations returned successfully. application/json object(2 fields)
401 Missing or invalid API key. application/json object(1 fields)
403 Workspace is deactivated. application/json object(1 fields)
429 Rate limit exceeded. application/json object(1 fields)
500 Internal server error. application/json object(1 fields)
Response 200 (application/json)
{
  "data": [
    {
      "id": 974,
      "sourceAdId": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
      "type": "VIDEOTOSTORYBOARD",
      "briefId": null,
      "form": {
        "isTrusted": true
      },
      "result": [
        {
          "type": "Clip",
          "description": "Close-up of hands placing a tracker on a food item at a beach.",
          "details": [
            "Close-up shot",
            "Ocean and sand in background",
            "Natural sunlight"
          ]
        },
        {
          "type": "Screen Recording",
          "description": "Phone map view showing movement from sea to land.",
          "details": [
            "Map zoom effect",
            "Location pin animation"
          ]
        },
        {
          "type": "Graphic",
          "description": "Contact card with property details and agent info.",
          "details": [
            "Address and name",
            "Brand logo lockup"
          ]
        }
      ],
      "status": "DONE",
      "creditsUsed": 4,
      "workspaceId": 412,
      "userId": 91,
      "createdAt": "2026-03-05T01:00:10.993Z"
    },
    {
      "id": 963,
      "sourceAdId": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
      "type": "VIDEOTOSTORYBOARD",
      "briefId": null,
      "form": {
        "isTrusted": true
      },
      "result": null,
      "status": "FAILED",
      "creditsUsed": 0,
      "workspaceId": 412,
      "userId": 91,
      "createdAt": "2026-03-04T08:20:11.762Z"
    },
    {
      "id": 944,
      "sourceAdId": "ab4f7e00-7f8c-4a8f-a84d-8d20f0a877ab",
      "type": "COPY",
      "briefId": 3,
      "form": {
        "isTrusted": true
      },
      "result": {
        "copy": "We launched our ad library in days and now our team can search ads, tags, and transcripts in one place."
      },
      "status": "DONE",
      "creditsUsed": 1,
      "workspaceId": 412,
      "userId": 91,
      "createdAt": "2025-10-17T08:21:08.274Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 100,
    "count": 8,
    "total": 8,
    "totalPages": 1
  }
}
Response 401 (application/json)
{
  "error": "Missing Bearer token"
}
Response 403 (application/json)
{
  "error": "Workspace is deactivated. Please select a plan to use the API."
}
Response 429 (application/json)
{
  "error": "Rate limit exceeded"
}
Response 500 (application/json)
{
  "error": "Internal server error"
}
GET /api/v1/boards

List boards

List boards

Get boards in your workspace. This is useful for building simple UI dropdowns and board pickers. Authentication: - Header: `Authorization: Bearer sk_<16_lowercase_alnum>` Workspace requirements: - Use this API with trial or active paid workspaces. - Deactivated workspaces receive `403`. Rate limits: - Up to 120 requests/min before delay. - Hard cap at 200 requests/min (`429`).

Parameters

Name In Required Type Description
page query No integer Page number (default 1). Page size is fixed at 100.

Request Body

No request body.

Responses

Status Description Content types Schema
200 Boards returned successfully. application/json object(2 fields)
401 Missing or invalid API key. application/json object(1 fields)
403 Workspace is deactivated. application/json object(1 fields)
429 Rate limit exceeded. application/json object(1 fields)
500 Internal server error. application/json object(1 fields)
Response 200 (application/json)
{
  "data": [
    {
      "id": 901,
      "name": "Winning Concepts",
      "slug": "winning-concepts-2a4f71-board",
      "description": null,
      "public": true,
      "shareable": false,
      "order": 0,
      "folderId": 400,
      "createdAt": "2025-08-11T06:46:25.794Z",
      "updatedAt": "2025-09-01T09:13:07.801Z"
    },
    {
      "id": 905,
      "name": "Secret Competitor Notes",
      "slug": "secret-competitor-notes-8f92d1-board",
      "description": null,
      "public": false,
      "shareable": false,
      "order": 7,
      "folderId": 400,
      "createdAt": "2025-03-19T01:33:25.420Z",
      "updatedAt": "2025-09-01T08:25:52.882Z"
    },
    {
      "id": 909,
      "name": "Static Ad Vault",
      "slug": "static-ad-vault-31cc8a-board",
      "description": "High-performing static ads from Facebook and Instagram.",
      "public": true,
      "shareable": false,
      "order": 4,
      "folderId": 400,
      "createdAt": "2024-07-12T06:54:25.361Z",
      "updatedAt": "2025-09-01T08:25:52.882Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 100,
    "count": 22,
    "total": 22,
    "totalPages": 1
  }
}
Response 401 (application/json)
{
  "error": "Missing Bearer token"
}
Response 403 (application/json)
{
  "error": "Workspace is deactivated. Please select a plan to use the API."
}
Response 429 (application/json)
{
  "error": "Rate limit exceeded"
}
Response 500 (application/json)
{
  "error": "Internal server error"
}
GET /api/v1/folders

List folders

List folders

Get folders in your workspace. Authentication: - Header: `Authorization: Bearer sk_<16_lowercase_alnum>` Workspace requirements: - Use this API with trial or active paid workspaces. - Deactivated workspaces receive `403`. Rate limits: - Up to 120 requests/min before delay. - Hard cap at 200 requests/min (`429`).

Parameters

Name In Required Type Description
page query No integer Page number (default 1). Page size is fixed at 100.

Request Body

No request body.

Responses

Status Description Content types Schema
200 Folders returned successfully. application/json object(2 fields)
401 Missing or invalid API key. application/json object(1 fields)
403 Workspace is deactivated. application/json object(1 fields)
429 Rate limit exceeded. application/json object(1 fields)
500 Internal server error. application/json object(1 fields)
Response 200 (application/json)
{
  "data": [
    {
      "id": 47931,
      "name": "Seasonal Concepts",
      "default": false,
      "hidden": false,
      "order": 2,
      "createdAt": "2025-09-30T01:25:17.559Z"
    },
    {
      "id": 400,
      "name": "Default",
      "default": true,
      "hidden": false,
      "order": 1,
      "createdAt": "2025-04-26T06:53:28.772Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 100,
    "count": 2,
    "total": 2,
    "totalPages": 1
  }
}
Response 401 (application/json)
{
  "error": "Missing Bearer token"
}
Response 403 (application/json)
{
  "error": "Workspace is deactivated. Please select a plan to use the API."
}
Response 429 (application/json)
{
  "error": "Rate limit exceeded"
}
Response 500 (application/json)
{
  "error": "Internal server error"
}
GET /api/v1/library

List library ads

List library ads

Get saved ads from your Swipekit library. This endpoint is great for beginners because it supports simple pagination and optional filters. Keep it simple at first: just call it with no filters, then add filters as you need them. Authentication: - Header: `Authorization: Bearer sk_<16_lowercase_alnum>` Workspace requirements: - Use this API with trial or active paid workspaces. - Deactivated workspaces receive `403`. Rate limits: - Up to 120 requests/min before delay. - Hard cap at 200 requests/min (`429`).

Parameters

Name In Required Type Description
page query No integer Page number (default 1). Uses library default page size when take is not supplied.
query query No string Search text.
skip query No integer Result offset.
take query No integer Number of records to return.
platform query No string Platform filter.
mediaType query No string Media type filter.
activeAds query No enum(0, 1, 2) Active ad filter.
sort query No string Sort mode.
tag query No string Return ads linked to this exact saved tag.
brands query No array<string> Brand name filters. Pass as repeated params (`brands=nike&brands=adidas`) or as comma-separated text.
networks query No array<string> Network filters (for example `facebook`, `instagram`, `tiktok`).
categories query No array<string> Category filters. Uses the same input format as `brands`.

Request Body

No request body.

Responses

Status Description Content types Schema
200 Library ads returned successfully. application/json object(2 fields)
401 Missing or invalid API key. application/json object(1 fields)
403 Workspace is deactivated. application/json object(1 fields)
429 Rate limit exceeded. application/json object(1 fields)
500 Internal server error. application/json object(1 fields)
Response 200 (application/json)
{
  "data": [
    {
      "id": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
      "workspaceId": 412,
      "userId": 91,
      "blockId": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
      "tags": null,
      "createdAt": "2026-03-10T03:42:15.220Z",
      "block": {
        "id": "9f24b6d1-3e82-43bf-bf27-7f6a9b3e7a10",
        "title": "Coastal Bay Retreat",
        "metaId": "590012345678900",
        "type": "facebook",
        "tags": [
          "Travel"
        ],
        "assets": [
          {
            "type": "image",
            "ratio": 0.6665,
            "assetPath": "fb-590012345678900-a1b2c3d4-1.jpeg"
          }
        ],
        "source": "https://www.facebook.com/coastalbayretreat/",
        "searchable": "Coastal Bay Retreat",
        "assetRatio": 1,
        "adCopy": "Sunrise walks, ocean views, and family time that actually feels like a holiday.",
        "assetType": "image",
        "endDate": "2026-03-09T08:00:00.000Z",
        "adTitle": "Your next family getaway starts here.",
        "categories": [
          "Travel"
        ],
        "networks": [
          "facebook",
          "instagram"
        ],
        "status": "INACTIVE",
        "statusCheckAt": "2026-03-11T12:17:20.100Z",
        "meta": {
          "cta": "MESSAGE_PAGE",
          "isEuAd": false,
          "displayFormat": "image"
        },
        "brandId": 30110,
        "rating": 1,
        "activeDays": 12,
        "ctaLink": null,
        "createdAt": "2026-03-10T03:42:15.211Z",
        "transcriptId": null,
        "brand": {
          "name": "Coastal Bay Retreat",
          "slug": "coastal-bay-retreat",
          "logo": "coastal-bay-retreat-avatar.jpeg"
        }
      },
      "boards": []
    },
    {
      "id": "7bde2f10-f8e9-4aa9-9d31-08f40c5d3d66",
      "workspaceId": 412,
      "userId": 91,
      "blockId": "7bde2f10-f8e9-4aa9-9d31-08f40c5d3d66",
      "tags": null,
      "createdAt": "2026-03-10T03:41:04.805Z",
      "block": {
        "id": "7bde2f10-f8e9-4aa9-9d31-08f40c5d3d66",
        "title": "Sparkle Soda AU",
        "metaId": "777001234560111",
        "type": "facebook",
        "tags": [
          "Brand"
        ],
        "assets": [
          {
            "type": "video",
            "cover": {
              "type": "image",
              "assetPath": "fb-777001234560111-b7c8d9-cover-1.webp"
            },
            "ratio": null,
            "assetPath": "fb-777001234560111-b7c8d9-1-video.mp4"
          }
        ],
        "source": "https://www.facebook.com/sparklesodaaustralia/",
        "searchable": "Sparkle Soda AU",
        "assetRatio": 1,
        "adCopy": "When the heat kicks in, turn up the refreshment.",
        "assetType": "video",
        "endDate": "2026-03-09T08:00:00.000Z",
        "adTitle": "Sparkle Summer",
        "categories": [
          "Brand"
        ],
        "networks": [
          "facebook"
        ],
        "status": "INACTIVE",
        "statusCheckAt": "2026-03-11T12:19:53.202Z",
        "meta": {
          "cta": "SHOP_NOW",
          "isEuAd": false,
          "displayFormat": "video"
        },
        "brandId": 30111,
        "rating": 1,
        "activeDays": 64,
        "ctaLink": "https://shop.example.com/products/sparkle-soda",
        "createdAt": "2026-03-10T03:41:04.799Z",
        "transcriptId": null,
        "brand": {
          "name": "Sparkle Soda AU",
          "slug": "sparkle-soda-au",
          "logo": "sparkle-soda-au-avatar.jpeg"
        }
      },
      "boards": []
    },
    {
      "id": "5c220aa9-17d0-4cf9-aaf6-2ec1b75eb5e1",
      "workspaceId": 412,
      "userId": 91,
      "blockId": "5c220aa9-17d0-4cf9-aaf6-2ec1b75eb5e1",
      "tags": [],
      "createdAt": "2026-03-10T03:38:20.019Z",
      "block": {
        "id": "5c220aa9-17d0-4cf9-aaf6-2ec1b75eb5e1",
        "title": "www.instagram.com",
        "metaId": "DQ2xyZ8LmN1",
        "type": "instagram-feed",
        "tags": null,
        "assets": [
          {
            "type": "video",
            "cover": {
              "type": "image",
              "assetPath": "DQ2xyZ8LmN1-0-cover.webp"
            },
            "ratio": 1.7777,
            "assetPath": "DQ2xyZ8LmN1-0-video.mp4"
          }
        ],
        "searchable": "www.instagram.com",
        "assetRatio": 1.7777,
        "adCopy": "A quick storytelling hook that drove high engagement.",
        "assetType": "video",
        "networks": [
          "instagram-feed",
          "instagram-reel"
        ],
        "comments": 210,
        "likes": 4821,
        "views": 145900,
        "status": "ACTIVE",
        "statusCheckAt": "2026-03-10T03:38:20.010Z",
        "meta": {
          "advertiser": {
            "name": "North Star Studio"
          }
        },
        "brandId": 30112,
        "rating": 1,
        "activeDays": 0,
        "ctaLink": null,
        "createdAt": "2026-03-10T03:38:20.010Z",
        "transcriptId": null,
        "brand": {
          "name": "North Star Studio",
          "slug": "north-star-studio",
          "logo": "north-star-studio-avatar.jpeg"
        }
      },
      "boards": [
        901,
        905
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "count": 20
  }
}
Response 401 (application/json)
{
  "error": "Missing Bearer token"
}
Response 403 (application/json)
{
  "error": "Workspace is deactivated. Please select a plan to use the API."
}
Response 429 (application/json)
{
  "error": "Rate limit exceeded"
}
Response 500 (application/json)
{
  "error": "Internal server error"
}
GET /api/v1/trackers

List trackers

List trackers

Get trackers for your workspace. Each tracker includes its related brand details. Authentication: - Header: `Authorization: Bearer sk_<16_lowercase_alnum>` Workspace requirements: - Use this API with trial or active paid workspaces. - Deactivated workspaces receive `403`. Rate limits: - Up to 120 requests/min before delay. - Hard cap at 200 requests/min (`429`).

Parameters

Name In Required Type Description
page query No integer Page number (default 1). Page size is fixed at 100.

Request Body

No request body.

Responses

Status Description Content types Schema
200 Trackers returned successfully. application/json object(2 fields)
401 Missing or invalid API key. application/json object(1 fields)
403 Workspace is deactivated. application/json object(1 fields)
429 Rate limit exceeded. application/json object(1 fields)
500 Internal server error. application/json object(1 fields)
Response 200 (application/json)
{
  "data": [
    {
      "id": 8101,
      "workspaceId": 412,
      "brandId": 70001,
      "status": "ACTIVE",
      "lastCheckedAt": "2026-03-11T09:02:14.431Z",
      "createdAt": "2026-01-29T03:11:42.528Z",
      "brand": {
        "id": 70001,
        "name": "Metro One Department Store",
        "slug": "metro-one-department-store",
        "category": "Shopping Mall",
        "logo": "metro-one-department-store-avatar.jpeg",
        "fbId": "230746680338335",
        "url": null
      }
    },
    {
      "id": 8102,
      "workspaceId": 412,
      "brandId": 70002,
      "status": "ACTIVE",
      "lastCheckedAt": "2026-03-11T15:42:09.303Z",
      "createdAt": "2026-01-29T03:03:12.259Z",
      "brand": {
        "id": 70002,
        "name": "SkinLab Co",
        "slug": "skinlab-co",
        "category": "Shopping",
        "logo": "skinlab-co-avatar.jpeg",
        "fbId": "108012461717543",
        "url": "skinlab.example"
      }
    },
    {
      "id": 8103,
      "workspaceId": 412,
      "brandId": 70003,
      "status": "ACTIVE",
      "lastCheckedAt": "2026-03-08T18:14:21.083Z",
      "createdAt": "2026-01-29T02:47:55.440Z",
      "brand": {
        "id": 70003,
        "name": "Luno Apparel",
        "slug": "luno-apparel",
        "category": "Clothing",
        "logo": "luno-apparel-avatar.jpeg",
        "fbId": "655031701026626",
        "url": "luno.example"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 100,
    "count": 9,
    "total": 9,
    "totalPages": 1
  }
}
Response 401 (application/json)
{
  "error": "Missing Bearer token"
}
Response 403 (application/json)
{
  "error": "Workspace is deactivated. Please select a plan to use the API."
}
Response 429 (application/json)
{
  "error": "Rate limit exceeded"
}
Response 500 (application/json)
{
  "error": "Internal server error"
}
GET /api/v1/usage

Get usage summary

Get usage summary

Get a simple usage payload for your workspace. The shape is intentionally straightforward for junior developers. Authentication: - Header: `Authorization: Bearer sk_<16_lowercase_alnum>` Workspace requirements: - Use this API with trial or active paid workspaces. - Deactivated workspaces receive `403`. Rate limits: - Up to 120 requests/min before delay. - Hard cap at 200 requests/min (`429`).

Parameters

No parameters.

Request Body

No request body.

Responses

Status Description Content types Schema
200 Usage returned successfully. application/json object(1 fields)
401 Missing or invalid API key. application/json object(1 fields)
403 Workspace is deactivated. application/json object(1 fields)
429 Rate limit exceeded. application/json object(1 fields)
500 Internal server error. application/json object(1 fields)
Response 200 (application/json)
{
  "data": [
    {
      "your_email": "[email protected]",
      "plan_type": "Basic",
      "billing_frequency": "monthly",
      "workspace_name": "Acme Growth",
      "account_activated": "Yes",
      "member_since": "2023-01-01T05:48:02.674Z",
      "total_ads_in_your_library": 665,
      "total_boards_in_your_workspace": 22,
      "total_folders_in_your_workspace": 2,
      "tracker_limit": 20,
      "ai_credits_used": 62,
      "ai_credits_on_your_plan": 150,
      "ai_credits_reset_date": "2026-01-13",
      "total_credits": 150,
      "remaining_credits": 88,
      "user": {
        "id": "91",
        "email": "[email protected]"
      }
    }
  ]
}
Response 401 (application/json)
{
  "error": "Missing Bearer token"
}
Response 403 (application/json)
{
  "error": "Workspace is deactivated. Please select a plan to use the API."
}
Response 429 (application/json)
{
  "error": "Rate limit exceeded"
}
Response 500 (application/json)
{
  "error": "Internal server error"
}

Upgrade your creative workflow

Save winning ads from every major library, keep the full context, and turn scattered inspiration into reusable creative direction.

Start free trial

HEC Wellness Center

Saved 2 months ago
The secret is out—Titanium Lifting is here to transform your skin. 🌟 #TitaniumLift #KoreanBeautySecrets #SkinTightening
Show more

HEC Wellness Center

Saved 2 months ago
The secret is out—Titanium Lifting is here to transform your skin. 🌟 #TitaniumLift #KoreanBeautySecrets #SkinTightening
Show more