Ads - Brandsearch API Reference

The ads endpoint lets you retrieve ad creatives and social media posts for any brand across Meta (Facebook/Instagram Ads), TikTok, and Instagram. On this page, we'll look at how to query ads with platform-specific filters and sorting.

The ad model

The ad model varies by platform. Below are the shared and platform-specific properties.

Shared properties

Name
_id
Type
string
Description
Unique identifier for the ad.
Name
brand_id
Type
string
Description
The brand this ad belongs to.
Name
platform
Type
string
Description
The platform: meta, tiktok, or instagram.

Meta ad properties

Name
ad_id
Type
string
Description
Meta Ad Library ID.
Name
status
Type
string
Description
Active or Inactive.
Name
content
Type
string
Description
The ad copy/text content.
Name
is_video
Type
boolean
Description
Whether the ad contains video.
Name
is_image
Type
boolean
Description
Whether the ad contains an image.
Name
start_date
Type
timestamp
Description
When the ad started running.
Name
eu_total_spend
Type
number
Description
Total EU spend in euros.
Name
eu_total_reach
Type
number
Description
Total EU reach (impressions).
Name
target_gender
Type
string
Description
Target gender demographic.
Name
target_ages
Type
string
Description
Target age range.
Name
funnel_type
Type
string
Description
Ad funnel classification (e.g., TOF, MOF, BOF).
Name
duration
Type
integer
Description
Video duration in seconds.

TikTok post properties

Name
desc
Type
string
Description
Post description/caption.
Name
play_count
Type
integer
Description
Number of views/plays.
Name
digg_count
Type
integer
Description
Number of likes.
Name
comment_count
Type
integer
Description
Number of comments.
Name
share_count
Type
integer
Description
Number of shares.
Name
engagement_rate
Type
number
Description
Engagement rate as a percentage.
Name
create_time
Type
timestamp
Description
When the post was created.

Instagram post properties

Name
code
Type
string
Description
Instagram shortcode.
Name
caption
Type
string
Description
Post caption text.
Name
like_count
Type
integer
Description
Number of likes.
Name
comment_count
Type
integer
Description
Number of comments.
Name
view_count
Type
integer
Description
Number of views (for video/reels).
Name
engagement_rate
Type
number
Description
Engagement rate as a percentage.
Name
is_reel
Type
boolean
Description
Whether the post is a Reel.
Name
taken_at
Type
timestamp
Description
When the post was published.

GET/v1/brands/:brand_id/ads

List ads for a brand

This endpoint allows you to retrieve a paginated list of ads or posts for a specific brand. The platform parameter is required.

Required attributes

Name
platform
Type
string
Description
The platform to query. One of: meta, tiktok, instagram.

Optional attributes

Name
page
Type
integer
Description
Page number. Default 1.
Name
page_size
Type
integer
Description
Results per page (1-100). Default 20.
Name
sort_by
Type
string
Description
Sort field. Varies by platform (see below).
Name
sort_order
Type
string
Description
asc or desc (default desc).
Name
fields
Type
string
Description
Comma-separated list of fields to include.

Meta sort fields

created_at, start_date, eu_total_spend, eu_total_reach, total_active_time, duration

Meta filters

Name
status
Type
string
Description
active or inactive.
Name
is_video
Type
boolean
Description
Filter by video ads.
Name
is_image
Type
boolean
Description
Filter by image ads.
Name
min_spend
Type
number
Description
Minimum EU spend.
Name
max_spend
Type
number
Description
Maximum EU spend.
Name
min_reach
Type
number
Description
Minimum EU reach.

TikTok / Instagram sort fields

TikTok: create_time, play_count, digg_count, comment_count, share_count, engagement_rate

Instagram: taken_at, like_count, comment_count, view_count, play_count, engagement_rate

TikTok / Instagram filters

Name
min_play_count
Type
integer
Description
Minimum play/view count.
Name
min_like_count
Type
integer
Description
Minimum like count.
Name
min_engagement_rate
Type
number
Description
Minimum engagement rate (0-100).

Request

GET

/v1/brands/nike.com/ads

curl -G https://api.brandsearch.co/v1/brands/nike.com/ads \
  -H "X-API-Key: bsk_your_api_key" \
  -d platform=meta \
  -d status=active \
  -d sort_by=eu_total_spend \
  -d page_size=2

Response — Meta ads

{
  "data": [
    {
      "_id": "abc123",
      "ad_id": "123456789",
      "brand_id": "nike.com",
      "status": "Active",
      "platform": "meta",
      "content": "Just Do It. Shop the latest collection.",
      "is_video": true,
      "is_image": false,
      "start_date": "2025-01-10T00:00:00Z",
      "eu_total_spend": 45000.00,
      "eu_total_reach": 2500000,
      "target_gender": "All",
      "target_ages": "18-65",
      "funnel_type": "TOF",
      "duration": 30
    },
    {
      "_id": "def456",
      // ...
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 2,
    "total": 245,
    "total_pages": 123
  }
}

cURL — TikTok posts

curl -G https://api.brandsearch.co/v1/brands/nike.com/ads \
  -H "X-API-Key: bsk_your_api_key" \
  -d platform=tiktok \
  -d sort_by=play_count \
  -d min_engagement_rate=5

Response — TikTok posts

{
  "data": [
    {
      "_id": "7321456789",
      "brand_id": "nike.com",
      "platform": "tiktok",
      "desc": "New Air Max drop. Link in bio.",
      "play_count": 12500000,
      "digg_count": 890000,
      "comment_count": 15200,
      "share_count": 45000,
      "engagement_rate": 7.6,
      "create_time": "2025-03-15T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 342,
    "total_pages": 18
  }
}