Facebook Creator Discovery API

Facebook Creator Discovery API

Updated: Apr 30, 2026
The Facebook Creator Discovery API offers robust data-driven discovery for Facebook’s creator ecosystem to help brands find the right creators for their partnership ads⁠ campaigns. Brands can evaluate creators for partnership ads using authenticated, real-time 1st party data.

Getting Started

Prerequisites

  • In order to use these APIs, you must ask users to grant permissions to your app, on behalf of the brands they are admins of, using Facebook Login.
  • Required permissions:
    • facebook_creator_marketplace_discovery
    • pages_show_list
  • When a brand admin initiates Facebook Login, Meta will check the brands' eligibility for Facebook Creator Discovery. If a brand is eligible but has not yet onboarded, the admin will be prompted to accept the Facebook Creator Discovery Terms of Service⁠ to complete onboarding.
IMPORTANT

To request these permissions from all users, your app must be a Business type app and both permissions must be approved for Advanced Access through the App Review process. Permissions with Standard Access can only be requested from app users who have a role on the requesting app, enabling you to submit the required App Review implementation evidence.

Apps with Standard Access to the facebook_creator_marketplace_discovery permission will only receive simulated (mocked) creator data when making API queries. To obtain real creator data, you must submit an App Review request and receive Advanced Access approval for the facebook_creator_marketplace_discovery permission.

Authentication & Access Tokens

curl -i -X GET "https://graph.facebook.com/creator_marketplace/creators/...&access_token={page_access_token}"

curl -i -X GET "https://graph.facebook.com/creator_marketplace/content/...&access_token={page_access_token}"
  1. Authenticate as a User: Log in with Facebook Login and obtain a User Access Token with the required permissions.
  2. Request the Page Access Token: Use the User Access Token to call the /me/accounts endpoint of the Graph API. This will return a list of Pages the user manages, each with its own Page Access Token.
  3. Use the Token: Use the Page Access Token in your Facebook Creator Discovery API requests.
  4. Leverage the Graph API Explorer for testing. Follow the Get started guide to learn more.

Rate Limits

The Facebook Creator Discovery API enforces rate limits at both the Facebook account level and the application level.
  • Account-level: Requests are capped at 2000 per user per rolling one-hour window
  • Application-level: Requests are capped at 10000 per app per rolling one-hour window
Parameter Data Type Description
limit
integer
The number of results per page.
Default Value: 10
Maximum Value: 50
before
string
Cursor identifier used to fetch results that come before a specific reference point in the data. The value of a cursor identifier can be obtained from a previous successful query response.
after
string
Cursor identifier used to fetch results that come after a specific reference point in the data. The value of a cursor identifier can be obtained from a previous successful query response.

Creators Endpoint

  • The Creators endpoint offers insights about creator profile information, content engagement data, and audience demographics.
  • For Creators to be discoverable through search, they must have opted-in to data sharing.
  • There may be a slight delay between filter values and real-time data.

Sample Requests

  • Retrieve insights about a creator’s profile, engagement, and audience:
GET /creator_marketplace/creators?creator_id={creator-id}&fields=creator_alias,creator_bio,...
  • Find creators using flexible filters and search criteria:
GET /creator_marketplace/creators?creator_categories={creator_category}&creator_countries={country_code}&query={query}

Parameters

Filter values are not case-sensitive.
Parameter Data Type Description
creator_id
string
The public profile or page id or alias of the creator.
Examples: Meta or 100044413150303
limit
int
The number of creators per page Default Value: 10 Maximum Value: 50
query
string
Free-form semantic text input (keywords/ categories) to help search for Creators whose content is similar to the input query. Accepts single words or even multi word phrases. Responses will be prioritized with creators with recent contents that are relevant to the input.
Examples: disney, basketball shoes, tech gadgets
Note: This is a recommended parameter for discovery over creator_categories
sort_by
string
The descending sort order of search results.
Values:  followers, relevance (default)
Note: does not apply to semantic search (any search using ?query=..) since that is sorted by relevance only
creator_categories
array[string]
The self-selected category of the creator. Supports multiple comma separated categories.
Note: While this is not an exhaustive list of creator categories, they cover the vast majority of them.
Values:  digital_creator, video_creator, artist, comedian, activity_general, entrepreneur, personal_blog, blogger, bands_musicians, person, athlete, gaming_video_creator, chef
creator_interests
array[string]
The predicted interests of the creator. Allows searching against the hierarchy from top-level interest to subinterest to sub-subinterest (if available).
Note: Coverage is currently limited, so not every creator will be filterable by this filter.
Values: see Available Interests for valid values
creator_countries
array[string]
ISO 3166-1 alpha-2⁠ country code of the creator. Supports multiple comma separated countries.
Values:  US, CA, GB, AR, AU, BR, DE, ES, FR, ID, IL, IN, JP, KR, MX, NL, NZ, TR
major_audience_age_bucket
string
The age group of most followers.
Values:  18-24, 25-34, 35-44, 45-54, 55-64, and 65_and_above
major_audience_gender
string
The gender of most followers.
Values:  male and female
major_audience_country
array[string]
ISO 3166-1 alpha-2⁠ country code of most followers.
follower_count
JSON
Creator follower count filter with subparameters, see Metric Search Filters for more details.
interaction_rate
JSON
Creator interaction rate filter with subparameters, see Metric Search Filters for more detail.
reach
JSON
Creator reach filter with subparameters, see Metric Search Filters for more details.
interactions
JSON
Creator interactions filter with subparameters, see Metric Search Filters for more details.
publishing_activity
JSON
Creator publishing activity filter with subparameters, see Metric Search Filters for more details.
views
JSON
Creator views filter with subparameters, see Metric Search Filters for more details.
creator_languages
array[string]
ISO 639-1⁠ language code of creator languages.
Examples: en, es
past_partnerships
array[string]
Partner(s) tagged by the creator in their posts. This includes organic posts and partnerships ads.
Example: J.crew Factory
Note: We support partial string matches, e.g. adida also returns adidas.
has_past_partnerships
bool
True if the creator has tagged partner pages through organic posts or partnerships ads.
Values:  true, false, 0, 1

Metric Search Filters

Format:
{min:<number>,max:<number>,time_range:"<string>",breakdown:"<string>"}
Sample queries:
creator_marketplace/creators?reach={min:1,max:50,time_range:"L28",breakdown:"follower"}
creator_marketplace/creators?interaction_rate={min:1.5,time_range:"L14"}
Please remember to use quotations (“”) on subparameter values (e.g. breakdown:"follower").
Subparameters
Parameter Data Type Description
min
Optional if max given
Number (int or float)
The minimum value of the metric to filter for.
maxOptional if min given
Number (int or float)
The maximum value of metric to filter for.
time_rangeOptional
String (see “Available Lookback and Breakdown Types” for available input)
The time range value of metric to filter for.
breakdownOptional
String (see “Available Lookback and Breakdown Types” for available input)
The breakdown value of metric to filter for.
Available Lookback and Breakdown Types
“L” stands for “Last”, so anywhere you see L followed by a number x, it stands for the last x days. For example, L90 is equivalent to “last 90 days”.
Metric Supported time_range (default: L28) Supported breakdown
reach
L1, L7, L14, L28, L90.
overall, follower, non_follower
interactions
L1, L7, L14, L28, L90.
overall, follower, non_follower
publishing_activity
L1, L7, L14, L28, L90.
overall, follower, non_follower
views
L1, L7, L14, L28, L90.
overall, follower, non_follower, reels, videos, photos, story, links, multi_photo, multi_media, live, text
interaction_rate
L7, L14, L28
overall
follower_count
N/A
N/A

Response Fields

By default, all response fields are hidden except for creator_id if no fields are specified. To receive additional fields in your response, you must explicitly request them using the fields=... parameter.
When querying by creator_id, if the creator has been invited but has not yet onboarded to the program, the response may include only a subset of fields.
Field Data Type Description
creator_id
string
Creator’s profile id
creator_display_name
string
Name of profile or page
creator_alias
string
Creator’s alias
creator_bio
string
Creator’s self-provided intro bio on their profile
creator_profile_url
url
Creator’s profile link
creator_profile_image_url
url
Creator’s profile image link
Disclaimer: this url has temporary retention.
creator_cover_photo_url
url
Creator’s profile cover photo link
Disclaimer: this url has temporary retention.
recent_content
array[Content response]
List of public content made by the creator in L28 (by default). Time ranges: L1, L7, L14, L28, L90
Capped at 90 posts or at limit if provided. Append .limit({number}) e.g. &fields=recent_content.limit(3) to only fetch 3 most recent posts.
Note: Prefer using the Content Insights API and filter by creator_id.
creator_follower_count
number
Creator’s follower count
creator_categories
array[string]
The self-selected category of the creator. Supports multiple comma separated categories.
Note: This is not an exhaustive list of categories. While this is not an exhaustive list of creator categories, they cover the vast majority of them.
Values:  digital_creator, video_creator, artist, comedian, activity_general, entrepreneur, personal_blog, blogger, bands_musicians, person, athlete, gaming_video_creator, chef
creator_interests
array[string]
Filter creators based on category list input. See the “Available Interests” table for supported values.
creator_email
string
Creator’s email, if available.
creator_gender
string
Creator’s gender, if available.
creator_age_bucket
string
Age bucket of the creator. Respects creator’s FB privacy settings; only available if creator is already sharing their birthday and birth year publicly on Facebook. Otherwise, this field will not be included in the response.
Values: 18-24, 25-34, 35-44, 45-54, 55-64, 65+, if available
Note: Coverage is currently limited, so not every creator will have this field.
creator_country
string
ISO 3166-1 alpha-2⁠ code for the country in which the creator is based.
Examples: US, CA
creator_languages
array[string]
ISO 639-1⁠ language code of creator languages.
Examples: en, es
past_partnerships
array[string]
Partner(s) tagged by the creator in their posts. This includes organic posts and partnerships ads.
Note: Creators can tag brands themselves, which does not necessarily imply brand endorsement.
insights
JSON, see Creator Insights Metrics section
Collection of creator-level metrics data

Creator Insights Metrics

Insights are included as a field (insights) within the Creator endpoint above. This field offers additional customizability with input parameters of its own.
These values are estimated⁠ and updated daily. The time zone will be determined by the user’s local time zone, or if unavailable, it will default to Pacific Time (Los Angeles).

Sample Request

GET /creator_marketplace/creators?creator_id={creator-id}&fields=insights.metrics().period().time_range()

Parameters

Parameter Data Type Description Defaults (no param input)
metricsRequired
enum, or comma separated list
List of queryable metrics. See “Available Metrics” table below.
No default. See “Available Metrics” table below.
period
enum
The interval to break the result into: day or overall; day would mean daily time series.
overall
time_range
enum
Supported time ranges: L1, L7, L14, L28, L90, lifetime.
L28 is the default, except for followers-metrics which default to lifetime.

Response Fields

Field Data Type Description
name
enum
Name of the metric
period
enum
Period for the metric query. Either day or overall. Most default to overall.
time_range
enum
Available values: L1, L7, L14, L28, L90, lifetime.
values
array[JSON]
Array of value or value_with_breakdown objects, depending on the type of metric. If the query is for overall period, then this array is length 1. Otherwise, the length of this field will match time_range.
value
(potential field within values)
number
The actual numeric result for the metric query. Can either represent a total over the time range or a single day’s value.
value_with_breakdown
(potential field within values)
JSON
A dictionary of breakdown to actual numeric result for that breakdown. Currently only represents a total over the time range.

Available Metrics

Values for metrics field Supported period(s) Supported time_range(s) Description
creator_views
overall, day
L1, L7, L14, L28, L90
The number of times the creator’s content was played or displayed for at least 1ms. Content includes reels, videos, posts, stories and ads.
creator_views_by_followers
overall
L1, L7, L14, L28, L90
The number of times the creator’s content was played or displayed. Content includes reels, videos, posts, stories, and ads. Views are presented as a percentage breakdown based on follower status.
Type of follower includes: follower, non_follower.
creator_views_by_content_type
overall
L1, L7, L14, L28, L90
The number of times the creator’s content was played or displayed for at least 1ms. Content includes reels, videos, posts, stories, and ads. Views are a percentage breakdown by content type.
Content types:  reels, videos, photos, story, links, multi_photo, multi_media, live, text
publishing_activity
overall, day
L1, L7, L14, L28, L90
The total number of text, photo reels and stories published by the creator on Facebook in the specified time frame. This includes deleted posts.
Note: for the overall period, values are updated once per day.
publishing_activity_by_content_type
overall
L1, L7, L14, L28, L90
The total number of text, photo reels and stories published by the creator on Facebook in the specified time frame. Displayed as a percentage breakdown of content type, including deleted posts.
Type of content includes: reels, videos, photos, story, links, multi_photo, multi_media, live, text
creator_interaction_rate
overall
L1, L7, L14, L28, L90
Percentage of post net interactions (reactions, shares, comments, saves) divided by post views, averaged across all public content in the selected period. This metric is estimated⁠.
creator_reach
overall, day
L1, L7, L14, L28, L90
Counts unique reach from organic, paid, and other sources (e.g., tags, check-ins, profile visits), including boosted content. This metric is estimated.
creator_reach_by_followers
overall
L1, L7, L14, L28, L90
Percentage breakdown of reach by follower status. Reach is de-duplicated across organic and paid distribution.
Types of follower include: follower, non_follower
creator_interactions
overall, day
L1, L7, L14, L28, L90
The number of reactions, saves, comments, shares and replies on this content. Content can include formats such as posts, stories and more.
creator_interactions_by_followers
overall
L1, L7, L14, L28, L90
Percentage breakdown of interactions by follower status.
Type of follower includes: follower, non_follower
followers_genders
overall
lifetime
The gender distribution of the creator’s followers.
followers_age_genders
overall
lifetime
The age and gender distribution of the creator’s followers.
Note: limit to 10 cities by default.
followers_top_countries
overall
lifetime
Audience concentration by country. Countries are returned in ISO 3166-1 alpha-2⁠ country code format.
Note: limited to top 10 countries.
followers_top_cities
overall
lifetime
Audience concentration by city.

Error Codes

error_subcode error_user_title error_user_msg
3961010
Could not load creator
The provided creator ID is invalid.
3961015
Creator not invited
Creator has not been invited yet.
3961014
Ineligible creator
Creator does not meet the criteria to join this program.
10
N/A
Data unavailable: Creator is not onboarded to Creator Marketplace insights sharing
3961016
Invalid metric type
Invalid metrics: check for typos or incorrect endpoint usage.
3961017
Invalid period type
The requested period type is not supported for one or more of the metric(s)
3961018
Invalid time range type
The requested time range type is not supported for one or more of the metric(s)
3961019
Invalid content type
The requested metrics have an unsupported content type.
3961021
Invalid value
The filter value {value} for {key} is not supported. Please refer to documentation.
3961022
Min Follower Count Greater Than Max Follower Count
Min follower count is greater than max follower count. Please make sure the min follower count is less than or equal to max follower count.
3961024
Invalid time range value
The time range value {value} for {key} is not supported. Current supported time range values are {supported_time_range_values}. Please refer to documentation.
3961025
Invalid min or max value
Invalid input range for {filter_key}. Please ensure both minimum and maximum values are non-negative and that the minimum value is less than or equal to the maximum value.

Examples

Get creator insights on two metrics
GET /creator_marketplace/creators?creator_id={creator-id}&fields=insights.metrics(creator_reach,creator_interactions)
Get daily time series
GET /creator_marketplace/creators?creator_id={creator-id}&fields=insights.metrics(creator_reach).period(day)
Get overall values with selected time range
GET /creator_marketplace/creators?creator_id={creator-id}&fields=insights.metrics(creator_reach).time_range(L90)
Get 3 most recent content (Note: prefer using the Content Endpoint and filter by creator_id and limit)
GET /creator_marketplace/creators?creator_id={creator-id}&fields=recent_content.limit(3)
Search for all creators in the US and limit 10 per page
GET /creator_marketplace/creators?creator_countries=US&limit=10
Search for creators that are related to Disney (limited to basic fields)
GET /creator_marketplace/creators?fields=creator_display_name,creator_bio,creator_profile_url,creator_follower_count,creator_onboarding_status,creator_categories&query=Disney
Search creators with creator reach of 100-5000 over the past 28 days.
GET /creator_marketplace/creators?reach={min:100,max:5000,time_range:"L28"}
Search creators with a followers percentage on creator reach of 1-50% over the past 14 days.
GET creator_marketplace/creators?reach={min:1,max:50,time_range:"L14",breakdown:"follower"}
Search for creators with a minimum of 100,000 followers
GET /creator_marketplace/creators?follower_count={min:100000}
Search for creators who are producing contents related to “cookies”, are from the US or CA, and have a minimum of 100,000 followers and a maximum of 1,000,000 followers.
GET /creator_marketplace/creators?query=cookies&creator_countries=US,CA&follower_count={min:100000,max:1000000}
Search for creators from US, and major audience age in the group 25-34, and major audience gender is female
GET /creator_marketplace/creators?creator_countries=US&major_audience_age_bucket=25-34&major_audience_gender=female

Available Interests

Not all interests are covered, and results may be limited with increased query specificity level.
Level 1 Level 2 Level 3 Level 4
FASHION_AND_STYLE
↳
FASHION
CLOTHING_AND_ACCESSORIES
FOOTWEAR
↳
BEAUTY
HAIR_AND_HAIR_CARE
NAILS_AND_NAIL_CARE
HAIRSTYLES_AND_TRENDS
ANIMALS_AND_PETS
↳
ANIMALS
MAMMALS
BIRDS
↳
PETS
DOGS
CATS
VEHICLES_AND_TRANSPORTATION
↳
GROUND_TRANSPORTATION
CARS_AND_TRUCKS
CARS
CAR_CULTURE_AND_DRIVING
↳
AVIATION
HEAVY_MACHINERY_VEHICLES
MOTORSPORTS
VEHICLES_AND_TRANSPORTATION_INDUSTRY
TRAVEL_AND_LEISURE_ACTIVITIES
↳
TRAVEL_DESTINATIONS
TRAVEL_AND_TOURISM_IN_THE_AMERICAS
TRAVEL_AND_TOURISM_IN_EUROPE
↳
VACATION_AND_LEISURE_ACTIVITIES
TOURIST_ATTRACTIONS
VISUAL_ARTS_ARCHITECTURE_AND_CRAFTS
VISUAL_ARTS
CRAFTS
FOOD_AND_DRINK
↳
FOODS
DESSERTS_AND_SWEETS
PRODUCE
BAKED_GOODS
MEATS_AND_SEAFOOD
PREPARED_FOODS_AND_DISHES
CAKES
↳
DRINKS
NON_ALCOHOLIC_BEVERAGES
COFFEE_DRINKS
SPORTS
↳
COMBAT_SPORTS
BASKETBALL
FOOTBALL_AMERICAN
FOOTBALL_SOCCER
FISHING
GOLF
WRESTLING
PERFORMING_ARTS
COMEDY
DANCE
STAND_UP_COMEDY
HOME_AND_GARDEN
↳
HORTICULTURE_AND_GARDENING
HOME_RENOVATION_AND_CONSTRUCTION
HOUSEHOLD_MANAGEMENT
INTERIOR_DESIGN
FURNITURE_APPLIANCES_AND_HOME_FUNISHINGS
GARDENING_AND_LANDSCAPING
MUSIC_AND_AUDIO
PODCASTS_AND_RADIO
MUSICAL_INSTRUMENTS
MUSICAL_PERFORMANCES
PODCASTS
BUSINESS_FINANCE_AND_ECONOMICS
GAMES_PUZZLES_AND_PLAY
TOYS
VIDEO_GAMES
TV_AND_MOVIES
TV_AND_MOVIES_CELEBRITIES
SCIENCE_AND_TECH
TECHNOLOGY

Content Endpoint

  • The Content endpoint offers detailed content insights and supports searching for Creator content using various filters and sorting methods.
  • For a post to be discoverable it must be a public post.
  • Non-Branded Content data is shared with all agencies/brands; Branded Content data is shared only with the sponsor Brand. In this API, Branded Content data is accessible with a page access token from that Brand.
  • Applied filters display results only for creators who have consented to data sharing.
  • There may be a slight delay between filter values and real-time data.

Sample Requests

Retrieve insights about a post
GET /creator_marketplace/content?content_id={content-id}
Find Creator content using flexible filters and search criteria
GET /creator_marketplace/content?creator_id={creator-id}

GET /creator_marketplace/content?reach={min:min-reach,max:max-reach}&sort_by=reactions&time_range={time-range}&content_type=reels

Parameters

Parameter Data Type Description
content_id
string
ID of the Facebook Content (this is either the numeric ID or encoded string from a URL, both will work)
Example: https://www.facebook.com/Meta/videos/886117876817680
https://www.facebook.com/Meta/posts/pfbid0zKakkLboMfE8tavYn8yfbunmPM9KAFKmmGuZTTFo62RDMDu2tPV9ctUfiXNbsGcal
creator_id
array[string]
The public profile or page ID or alias of the content creator. Supports multiple comma-separated IDs.
E.g. Meta or 100044413150303
sort_by
string
The descending sort order of search results.
Values:  create_time (default), clicks, comments, interactions, reach, reactions, shares, views
start_date
string
The start date (inclusive) for the publish time of the content you want to retrieve, in YYYY-MM-DD format.
Note: invited if creator_id filter is set
end_date
string
The end date (inclusive) for the publish time of the content you want to retrieve, in YYYY-MM-DD format.
Note: invited if creator_id filter is set
time_range
string
A preset time range for the query. Use this instead of start_date/end_date for convenience.
Values:  L1 (today), L7, L14, L28, L90
content_type
string
The type of content to filter by, case-insensitive. If not specified, all content types are included.
Values:  LINKS, LIVE, PHOTOS, REELS, TEXT, VIDEOS
views
JSON
Content views filter with subparameters, see Metric Search Filters for more details.
reach
JSON
Content reach filter with subparameters, see Metric Search Filters for more details.
interactions
JSON
Content interactions filter with subparameters, see Metric Search Filters for more details.
reactions
JSON
Content reactions filter with subparameters, see Metric Search Filters for more details.
comments
JSON
Content comments filter with subparameters, see Metric Search Filters for more details.
shares
JSON
Content shares filter with subparameters, see Metric Search Filters for more details.
clicks
JSON
Content clicks filter with subparameters, see Metric Search Filters for more details.

Metric Search Filters

Format:
{min:<number>,max:<number>}
Sample queries:
creator_marketplace/content?reach={min:1,max:50}
creator_marketplace/content?reactions={min:1,max:50}&comments={min:2}
Subparameters
Parameter Data Type Description
min
Optional if max given
Number (int or float)
The minimum value of the metric to filter for.
maxOptional if min given
Number (int or float)
The maximum value of metric to filter for.

Response Fields

The time zone will be determined by the user’s local time zone, or if unavailable, it will default to Pacific Time (Los Angeles).
When querying by content_id, if the creator has been invited but has not yet onboarded to the program, the response may include only a subset of fields.
Field Data Type Description
content_id
string
ID of the content, number or encoded string
creator_id
string
ID of the creator
content_type
string
The type of the content. Examples: REELS, VIDEOS, PHOTOS, TEXT, LINKS
Note: the pluralization for REELS, VIDEOS, TEXT is intentional. A post can be multimedia.
create_time
ISO 8601 string
The publish time of the content. Represented as a date time in ISO 8601 format.
tagged_brand
string
If the content tagged a business partner (sponsor), show the name of the sponsor’s Facebook page
content_url
url
The publicly accessible URL of the content
content_thumbnail_url
url
URL linking to picture of content thumbnail
Disclaimer: this url has temporary retention.
caption
string
Creator-generated text in the post.
insights
JSON, see Content Insights Metrics section
Collection of content-level metrics data
comments
array[Comment response]
List of comments received on a post ranked by reactions count descending.
Note: Comments count are capped at 10 and potential integrity concerns are hidden. "Reactions" include like, love, laugh, etc.

Content Insights Metrics

Insights are included as a field (insights) within the Content endpoint above. This field offers additional customizability with input parameters of its own.
These values are estimated⁠ and updated daily. The time zone will be determined by the user’s local time zone, or if unavailable, it will default to Pacific Time (Los Angeles).

Parameters

Parameter Data Type Description Defaults (no param input)
metricsRequired
enum, or comma separated list
List of queryable metrics. See “Available Metrics” table below.
No default. See “Available Metrics” table below.
period
enum
The interval to break the result into: day or overall; day would mean daily time series.
overall
time_range
enum
Supported time ranges: L1, L7, L14, L28, L90, lifetime.
L28 is the default, except for followers-metrics which default to lifetime.

Response Fields

Field Data Type Description
name
enum
Name of the metric
period
enum
Period for the metric query. Either day or overall. Most default to overall.
time_range
enum
Available values: L1, L7, L14, L28, L90, lifetime.
values
array[JSON]
Array of value or value_with_breakdown objects, depending on the type of metric. If the query is for overall period, then this array is length 1. Otherwise, the length of this field will match time_range.
value
(potential field within values)
number
The actual numeric result for the metric query. Can either represent a total over the time range or a single day’s value.
value_with_breakdown
(potential field within values)
JSON
A dictionary of breakdown to actual numeric result for that breakdown. Currently only represents a total over the time range.

Available Metrics

Values for metrics field Supported period(s) Supported time_range(s) Description
reach
overall
lifetime
The number of people who saw this content at least once. Reach is different from impressions, which may include multiple views of your content by the same people.
reach_by_followers_and_non_followers
overall
lifetime
Reach: The de-duplicated number of people who saw this content at least once.
Followers: % of followers that have reached this content.
Non-followers: % of non-followers that have reached this content.
views
overall
lifetime
The number of times this content was played or displayed for at least 1ms or the number of times the creator’s photo or text was on screen.
views_by_followers_and_non_followers
overall
lifetime
Views are displayed as a percentage-based breakdown of views by whether the account that saw the content is a follower or not.
views_by_paid_organic
overall
lifetime
Views are displayed as a percentage-based breakdown of views by whether the viewer saw the creator’s content organically or through ads.
clicks
overall
lifetime
The number of clicks on this post.
interactions
overall
lifetime
The number of reactions, comments, shares and saves on this post.
reactions
overall
lifetime
The number of reactions on this post.
reactions_by_paid_organic
overall
lifetime
Displayed as a percentage-based breakdown of reactions by whether the viewer saw the creator’s content organically or through ads.
comments
overall
lifetime
The number of comments on this post.
comments_by_paid_organic
overall
lifetime
Displayed as a percentage-based breakdown of comments by whether the viewer saw the creator’s content organically or through ads.
shares
overall
lifetime
The number of shares on this post.
shares_by_paid_organic
overall
lifetime
Displayed as a percentage-based breakdown of shares by whether the viewer saw the creator’s content organically or through ads.
saves
overall
lifetime
The number of saves on this post.
saves_by_paid_organic
overall
lifetime
Displayed as a percentage-based breakdown of saves by whether the viewer saw the creator’s content organically or through ads.

Content Comments

Comments are included as a field (comments) within the Content endpoint above.

Response Fields

Field Data Type Description
comment_id
string
ID of the comment.
comment_text
string
Text associated by comment body text.
Note:  comment_text is empty when there is not text included in the comment (i.e. stickers, GIFs, etc).
comment_url
url
url linking to specified comment on the post.
Note: Only post format is supported currently while Reels url will link to the reel itself.

Error Codes

error_subcode error_user_title error_user_msg
3961009
Could not load content
The provided content ID is invalid or you do not have permission to access it. Please ensure that the content is public.
3961015
Creator not invited
The creator has not been invited yet.
3961014
Ineligible creator
The creator does not meet the criteria to join this program.
3961024
Invalid time range value
The time range value is not supported.
3961025
Invalid min or max value
Invalid input range for {filter-key}. Please ensure both minimum and maximum values are non-negative and that the minimum value is less than or equal to the maximum value.
3961026
Content ID filter can’t be used with other filter parameters
The content_id filter can’t be used with other filter parameters.
3961027
At least one filter is required
At least one filter is required for this query to search for valid results.
3961028
Invalid time range query
You can’t use start/end date filters together with the time range filter. Please refer to documentation.
10
N/A
Data unavailable: Creator is not onboarded to Creator Marketplace insights sharing
3961016
Invalid metric type
One or more of the requested metrics are invalid. There may be a typo, or you are trying to request content metrics for the creator endpoint, or vice versa.
3961017
Invalid period type
The requested period type is not supported for one or more of the metric(s)
3961018
Invalid time range type
The requested time range type is not supported for one or more of the metric(s)
3961019
Invalid content type
The requested metrics have an unsupported content type.

Examples

Get multiple metrics insights for a post
GET /creator_marketplace/content?content_id={content-id}&fields=insights.metrics(reach,views,comments_by_paid_organic)
Get comments text for a post
GET creator_marketplace/content?content_id={content-id}&fields=comments.fields(comment_text)
Get views by paid/organic breakdown for a post
GET /creator_marketplace/content?content_id={content-id}&fields=insights.metrics(views_by_paid_organic)
Search for posts from specific creators, with a minimum reach, sorted by reactions, published in the last 7 days and filtered to photo posts only
GET creator_marketplace/content?creator_id={creator-id-1},{creator-id-2}&reach={min:500}&sort_by=reactions&time_range=L7&content_type=PHOTOS
Search for posts sorted by number of comments, published in the last 14 days and return the content url and caption
GET creator_marketplace/content?sort_by=comments&time_range=L14&fields=content_url,caption