Swipe

Swipe endpoints expose the authenticated user's collections inside the Brandsearch app — Saved Ads, Saved Advertisers, Tracked Brands — and the boards that group them. Use them to pull a user's saved items into your own workflows.

Swipe endpoints require the API key's account to be linked to a Brandsearch user. If your account has not been provisioned yet, requests return 403 swipe_not_provisioned.

There are three folder types:

  • Ads folders (/v1/swipe/ads-folders) — collections of saved Meta / TikTok / Instagram ads
  • Brands folders (/v1/swipe/brands-folders) — collections of saved advertisers (by Meta page ID)
  • Spectre folders (/v1/swipe/spectre-folders) — collections of tracked brands

For each folder type there are 3 endpoints — list folders, get folder (returns saved item IDs), and resolve to records (returns full ad / brand objects). Folder listing and item-listing endpoints are unmetered. Resolution endpoints charge 1 credit per returned row.

A _swipe field is attached to every resolved record so you can correlate the public ad/brand back to the saved-item entry that referenced it.

Ads folders

Create an ads folder

Create a new ads folder for the authenticated user. Counts as 1 request against your daily/monthly quota; does not charge credits. Folders created via the API appear immediately in the dashboard.

Body parameters

  • Name
    name
    Type
    string
    Description

    Display name for the folder. 1-100 characters. Names must be unique per user — re-using a name returns 409 swipe_folder_name_taken.

Each user has a folder cap (default 100 per type, raise on request). Over the cap returns 429 swipe_folder_quota_exceeded with details.current and details.limit.

Rate limit

A hard per-key rate limit applies on top of the global one: 1 request/second and 5 requests/minute — per endpoint type. The brands and spectre create endpoints have their own independent buckets, so hitting all three in parallel allows up to 3 req/s and 15 req/min total. Over either window returns the standard 429 rate_limited envelope with Retry-After and the X-RateLimit-* headers pointing at the tighter bucket.

Request

POST
/v1/swipe/ads-folders
curl https://api.brandsearch.co/v1/swipe/ads-folders \
  -H "X-API-Key: bsk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q4 Black Friday"}'

201 Created

{
  "id": "ckxa1b2c3d4e5f6g7h8i9j0k",
  "name": "Q4 Black Friday",
  "short_id": 42,
  "item_count": 0,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

Save an ad to a folder

Save an ad to one of your folders. Mirrors the dashboard's "save ad" flow.

Dedup is per (url, user): re-saving the same URL reuses the existing saved-ad record and just attaches it to the folder you specify. Idempotent on re-save: if the ad is already in the target folder, the response is still 201 with already_in_folder: true — no error.

Counts as 1 request against your daily/monthly quota; does not charge credits.

Path parameters

  • Name
    folder_id
    Type
    string
    Description

    Folder ID (1-64 chars). The folder must be owned by the authenticated user — folders owned by someone else return 404 swipe_folder_not_found.

Body parameters

  • Name
    url
    Type
    string
    Description

    The ad's source URL. Used as the dedup key alongside the user.

  • Name
    type
    Type
    string
    Description

    Platform the ad came from. Must be meta, tiktok, or instagram. The alias facebook is accepted and normalised to meta server-side.

  • Name
    ad_id
    Type
    string
    Description

    Optional platform-specific ad identifier (Meta ad library ID, TikTok ID, etc.). Stored as-is on the saved-ad record; not used for dedup.

Quota

Each user has a saved-ads cap (default 5; raise on request). Creating a new saved-ad row that pushes you past the cap returns 429 swipe_item_quota_exceeded with details.item_type, details.current, and details.limit. Adding an already-saved ad to an additional folder does NOT consume save-quota — only the first save of a given URL does.

Rate limit

Same hard per-key limit as the folder-create endpoints: 1 request/second and 5 requests/minute on this endpoint. Brands and spectre save endpoints have their own buckets.

Request

POST
/v1/swipe/ads-folders/:folder_id/items
curl https://api.brandsearch.co/v1/swipe/ads-folders/ckxa1b2c3d4e5/items \
  -H "X-API-Key: bsk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://facebook.com/ads/library/?id=123",
    "type": "meta",
    "ad_id": "123"
  }'

201 Created

{
  "saved_ad_id": "cky1z2a3b4c5d6e",
  "url": "https://facebook.com/ads/library/?id=123",
  "type": "meta",
  "ad_id": "123",
  "added_at": "2026-05-23T10:00:00Z",
  "folder_id": "ckxa1b2c3d4e5",
  "already_in_folder": false
}

List ads folders

Paginated list of the authenticated user's Saved Ads folders. Unmetered.

Standard page / page_size pagination apply.

Request

GET
/v1/swipe/ads-folders
curl -G https://api.brandsearch.co/v1/swipe/ads-folders \
  -H "X-API-Key: bsk_your_api_key"

Response

{
  "data": [
    { "id": "fold_abc123", "name": "Q4 Black Friday", "item_count": 42 },
    { "id": "fold_def456", "name": "Skincare creatives", "item_count": 18 }
  ],
  "pagination": {"page": 1, "page_size": 20, "total": 2, "total_pages": 1}
}

Get an ads folder

Folder metadata + saved-ad items (ID and platform only — call /ads to resolve them to records). Unmetered.

Path parameters

  • Name
    folder_id
    Type
    string
    Description

    Folder ID (1-64 chars).

Returns 404 swipe_folder_not_found if the folder is not owned by the authenticated user.

Request

GET
/v1/swipe/ads-folders/:folder_id
curl https://api.brandsearch.co/v1/swipe/ads-folders/fold_abc123 \
  -H "X-API-Key: bsk_your_api_key"

Response

{
  "id": "fold_abc123",
  "name": "Q4 Black Friday",
  "item_count": 2,
  "items": [
    {"saved_ad_id": "sa_001", "ad_id": "123456789", "platform": "meta", "added_at": "2026-04-15T10:00:00Z"},
    {"saved_ad_id": "sa_002", "ad_id": "7321456789", "platform": "tiktok", "added_at": "2026-04-16T14:00:00Z"}
  ]
}

Resolve folder ads to records

Resolve every saved ad in the folder to its public record. Per-platform resolution is automatic — Meta items hit Meta data, TikTok items hit TikTok data, etc. Items we can't find (e.g., deleted ads) are skipped silently.

Each returned record gets a _swipe block with the saved-ad id, platform, and added_at timestamp.

Charges 1 credit per returned row.

Optional attributes

  • Name
    fields
    Type
    string
    Description

    Comma-separated field allowlist applied across all platforms.

Request

GET
/v1/swipe/ads-folders/:folder_id/ads
curl -G https://api.brandsearch.co/v1/swipe/ads-folders/fold_abc123/ads \
  -H "X-API-Key: bsk_your_api_key" \
  -d page_size=20

Response

{
  "data": [
    {"id": "abc123", "brand_id": "nike.com", "status": "Active", "creative": {"title": "Just Do It.", "description": "Shop the latest collection.", "cta": {"text": "Shop now", "type": "SHOP_NOW"}}, "_swipe": "..."}
  ],
  "pagination": {"page": 1, "page_size": 20, "total": 42, "total_pages": 3}
}

Each row's _swipe block contains saved_ad_id, platform, and added_at.

Brands folders (Saved Advertisers)

Create a brands folder

Create a new brands folder for the authenticated user. Same shape as POST /v1/swipe/ads-folders — body is { name }, 1 request charged, 0 credits. Names are unique per user; duplicates return 409 swipe_folder_name_taken. Folder cap (default 100) over-limit returns 429 swipe_folder_quota_exceeded. Same hard rate limit: 1 req/s and 5 req/min on this endpoint.

Request

POST
/v1/swipe/brands-folders
curl https://api.brandsearch.co/v1/swipe/brands-folders \
  -H "X-API-Key: bsk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Skincare competitors"}'

201 Created

{
  "id": "ckxa1b2c3d4e5f6g7h8i9j0k",
  "name": "Skincare competitors",
  "short_id": 7,
  "item_count": 0,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

Save an advertiser to a folder

Save a Meta advertiser (page id) to one of your brands folders. Dedup is per (advertiser_id, user): re-saving the same advertiser reuses the existing record. Idempotent on re-save: already in the target folder returns 201 with already_in_folder: true.

Counts as 1 request against your daily/monthly quota; does not charge credits.

Path parameters

  • Name
    folder_id
    Type
    string
    Description

    Folder ID (1-64 chars). Must be owned by the authenticated user — otherwise 404 swipe_folder_not_found.

Body parameters

  • Name
    advertiser_id
    Type
    string
    Description

    The Meta page id (a numeric string). Same value you get from /v1/brands/{id}/advertisers or the page identifier in the Meta Ads Library.

No per-user save-quota is enforced on advertisers (intentional behavioural parity with the dashboard). The folder cap on POST /v1/swipe/brands-folders still bounds how many brands folders a user can create.

Rate limit

1 request/second and 5 requests/minute on this endpoint, separate bucket from the ads and spectre save endpoints.

Request

POST
/v1/swipe/brands-folders/:folder_id/items
curl https://api.brandsearch.co/v1/swipe/brands-folders/ckxa1b2c3d4e5/items \
  -H "X-API-Key: bsk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"advertiser_id": "100064123456789"}'

201 Created

{
  "saved_advertiser_id": "cky1z2a3b4c5d6e",
  "advertiser_id": "100064123456789",
  "added_at": "2026-05-23T10:00:00Z",
  "folder_id": "ckxa1b2c3d4e5",
  "already_in_folder": false
}

List brands folders

Paginated list of the authenticated user's Saved Advertisers folders. Saved advertisers are stored as Meta page IDs and resolved to brand records on demand. Unmetered.

Request

GET
/v1/swipe/brands-folders
curl https://api.brandsearch.co/v1/swipe/brands-folders \
  -H "X-API-Key: bsk_your_api_key"

Get a brands folder

Folder metadata + saved-advertiser items (each item carries an advertiser_id — a Meta page ID). Unmetered.

Returns 404 swipe_folder_not_found if the folder is not owned by the authenticated user.

Item shape

{
  "saved_advertiser_id": "sav_001",
  "advertiser_id": "15087023444",
  "added_at": "2026-04-15T10:00:00Z"
}

Resolve folder advertisers to brands

Resolve every saved advertiser to its brand record. Returns one brand per advertiser; advertisers that don't map to a known brand are skipped. Each returned brand gets a _swipe block with the saved-advertiser id, the original advertiser id, and added_at.

Charges 1 credit per returned row.

Optional attributes

  • Name
    fields
    Type
    string
    Description

    Comma-separated brand fields to include.

  • Name
    exclude_fields
    Type
    string
    Description

    Comma-separated brand fields to exclude.

Request

GET
/v1/swipe/brands-folders/:folder_id/brands
curl -G https://api.brandsearch.co/v1/swipe/brands-folders/fold_xyz/brands \
  -H "X-API-Key: bsk_your_api_key" \
  -d fields=name,monthly_visits,niche

Response

{
  "data": [
    {"name": "Nike", "monthly_visits": 150000000, "niche": "Fashion", "_swipe": "..."}
  ],
  "pagination": {"page": 1, "page_size": 20, "total": 12, "total_pages": 1}
}

Each brand's _swipe block contains saved_advertiser_id, advertiser_id, and added_at.

Spectre folders (Tracked Brands)

Create a spectre folder

Create a new spectre folder for the authenticated user. Same shape as the other create endpoints — body is { name }, 1 request charged, 0 credits. Names are unique per user; duplicates return 409 swipe_folder_name_taken. Folder cap (default 100) over-limit returns 429 swipe_folder_quota_exceeded.

Request

POST
/v1/swipe/spectre-folders
curl https://api.brandsearch.co/v1/swipe/spectre-folders \
  -H "X-API-Key: bsk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Brands to watch"}'

201 Created

{
  "id": "ckxa1b2c3d4e5f6g7h8i9j0k",
  "name": "Brands to watch",
  "short_id": 3,
  "item_count": 0,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

Save a tracked brand to a folder

Save a tracked brand to one of your spectre folders. Two mutually-exclusive modes mirror the dashboard's two add-flows:

  • Meta Ads Library mode — body: { url, page_id }. url must point at facebook.com/ads/library/…. Dedup per (url, user).
  • Track Creatives mode — body: { brand_id, scrapman_id }. Dedup per (brand_id, user).

Providing neither pair, both pairs, or a non-Meta url all return 400 validation_error. Idempotent on re-save: already in the target folder returns 201 with already_in_folder: true.

Counts as 1 request against your daily/monthly quota; does not charge credits.

Path parameters

  • Name
    folder_id
    Type
    string
    Description

    Folder ID (1-64 chars). Must be owned by the authenticated user — otherwise 404 swipe_folder_not_found.

Body parameters

  • Name
    url
    Type
    string
    Description

    Meta Ads Library URL. Required in Meta-mode. Must contain facebook.com/ads/library/.

  • Name
    page_id
    Type
    string
    Description

    Meta page identifier associated with url. Required in Meta-mode.

  • Name
    brand_id
    Type
    string
    Description

    Brand identifier in the catalogue (cleaned domain, e.g. nike.com). Required in Creatives-mode.

  • Name
    scrapman_id
    Type
    string
    Description

    Source-side scraping identifier paired with brand_id. Required in Creatives-mode.

Quota

Each user has a tracked-brands cap on the user profile (trackedBrandsQuota, default 0 — most users will need it raised). Creating a new tracked-brand record past the cap returns 429 swipe_item_quota_exceeded. Linking an already-tracked brand to another folder does NOT consume this quota.

Rate limit

1 request/second and 5 requests/minute on this endpoint, separate bucket from ads and brands save endpoints.

Request

POST
/v1/swipe/spectre-folders/:folder_id/items
curl https://api.brandsearch.co/v1/swipe/spectre-folders/ckxa1b2c3d4e5/items \
  -H "X-API-Key: bsk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://facebook.com/ads/library/?id=42",
    "page_id": "100064123456789"
  }'

201 Created

{
  "tracked_brand_id": "cky1z2a3b4c5d6e",
  "url": "https://facebook.com/ads/library/?id=42",
  "page_id": "100064123456789",
  "brand_id": null,
  "scrapman_id": null,
  "added_at": "2026-05-23T10:00:00Z",
  "folder_id": "ckxa1b2c3d4e5",
  "already_in_folder": false
}

List spectre folders

Paginated list of the authenticated user's Tracked Brands folders. Unmetered.

Request

GET
/v1/swipe/spectre-folders
curl https://api.brandsearch.co/v1/swipe/spectre-folders \
  -H "X-API-Key: bsk_your_api_key"

Get a spectre folder

Folder metadata + tracked-brand items. Each item carries a tracked_brand_id plus the brand reference used when it was tracked — typically a brand_id (the domain) or, as a fallback, a url. Unmetered.

Returns 404 swipe_folder_not_found if the folder is not owned by the authenticated user.

Item shape

{
  "tracked_brand_id": "tb_001",
  "brand_id": "nike.com",
  "url": null,
  "added_at": "2026-04-15T10:00:00Z"
}

Resolve folder ads

Resolve every tracked brand in the folder to its Meta ads — a one-call way to pull "show me the latest creatives from everyone I'm tracking". Per-tracked-brand fan-out is capped by max_ads_per_brand so one prolific brand doesn't drown out the others.

Each returned ad gets a _swipe block with tracked_brand_id, brand_id, and added_at so you can correlate ads back to the tracked brand entry that pulled them in.

Default fields include duration and has_transcript. When has_transcript=true, the ad also carries a transcript_url — fetch that URL to get a JSON transcript of the ad.

Charges 1 credit per returned row, matching /v1/brands/{id}/ads.

Optional attributes

  • Name
    max_ads_per_brand
    Type
    integer
    Description

    Max ads to pull per tracked brand (1-50, default 20).

  • Name
    status
    Type
    string
    Description

    active or inactive. Default: include both.

  • Name
    is_video
    Type
    boolean
    Description

    Filter by video ads.

  • Name
    is_image
    Type
    boolean
    Description

    Filter by image ads.

  • Name
    sort_by
    Type
    string
    Description

    Same Meta sort fields as /v1/brands/{id}/ads.

  • Name
    sort_order
    Type
    string
    Description

    asc or desc (default desc).

  • Name
    fields
    Type
    string
    Description

    Comma-separated Meta ad fields to include.

Request

GET
/v1/swipe/spectre-folders/:folder_id/ads
curl -G https://api.brandsearch.co/v1/swipe/spectre-folders/fold_xyz/ads \
  -H "X-API-Key: bsk_your_api_key" \
  -d max_ads_per_brand=10 \
  -d status=active \
  -d sort_by=eu_total_spend

Response

{
  "data": [
    {"id": "abc123", "brand_id": "nike.com", "duration": 30, "has_transcript": true, "transcript_url": "https://...", "_swipe": "..."}
  ],
  "pagination": {"page": 1, "page_size": 20, "total": 280, "total_pages": 14}
}

Each row's _swipe block contains tracked_brand_id, brand_id, and added_at.

Resolve folder to brands

Resolve every tracked brand to its brand record. Resolution tries the strongest identifier first — brand_id, then a fallback alias, then url. Items that don't resolve are skipped. Each returned brand gets a _swipe block with the tracked-brand id and added_at.

Charges 1 credit per returned row.

Same fields / exclude_fields options as brands folders above.

Request

GET
/v1/swipe/spectre-folders/:folder_id/brands
curl -G https://api.brandsearch.co/v1/swipe/spectre-folders/fold_xyz/brands \
  -H "X-API-Key: bsk_your_api_key"

Boards

Get a board

A board groups multiple folders into a workspace (e.g., a research board that bundles a Saved Ads folder, a Saved Advertisers folder, and a Tracked Brands folder). This endpoint returns the board metadata + each linked directory.

Each section identifies its directory type via directory.type, which is one of: saved_ads, saved_advertisers, tracked_brands, landing_pages.

Unmetered. Returns 404 swipe_board_not_found if the board is not owned by the authenticated user.

Request

GET
/v1/swipe/boards/:board_id
curl https://api.brandsearch.co/v1/swipe/boards/board_001 \
  -H "X-API-Key: bsk_your_api_key"

Response

{
  "id": "board_001",
  "name": "Q4 Beauty Research",
  "sections": [
    {"directory": "..."},
    {"directory": "..."}
  ]
}

Each directory object contains type (one of saved_ads, saved_advertisers, tracked_brands, landing_pages), id, name, and item_count.

Errors

CodeHTTPDescription
swipe_not_provisioned403The API key's account has not been linked to a Brandsearch user.
swipe_folder_not_found404The folder does not exist, or is not owned by the authenticated user.
swipe_board_not_found404The board does not exist, or is not owned by the authenticated user.

Was this page helpful?