Creator Marketplace Discovery API
Updated: Sep 22, 2026
Copy for LLM
New: the Discovery API now returns Facebook creators. Creator search covers creators who publish on Facebook as well as Instagram. Instagram remains the default everywhere in this API — on the
platform parameter of a creator search, and on .platform() for the insights field and the recent_media edge — so requests you make today return exactly what they return now. Facebook data is always opt-in.Creator Marketing Hub is where you can discover and evaluate Instagram and Facebook creators for partnership ads. The API offers personalized creator recommendations and search using authenticated, real-time first-party data to help your brand find the right creators for your partnership ad campaigns.
Before you begin
Permissions
To use these APIs, permissions must be granted using Facebook Login. These permissions are required to access the creator marketplace API:
instagram_creator_marketplace_discoveryinstagram_basicpages_manage_metadatapages_show_listbusiness_management
Note: For the
instagram_creator_marketplace_discovery permission, your app must have advanced access, which requires app review. When you first get access to instagram_creator_marketplace_discovery permission, you will be auto-granted standard access. Standard access will give you access to test data for testing and implementation purposes.Eligibility
In the brand onboarding flow, Meta will check if your brand is eligible for Instagram’s creator marketplace. If your brand is eligible but has not onboarded to the creator marketplace, you will need to accept the Instagram Creator Marketplace Terms of Service.
Access Tokens
This API requires a Page access token for a Page that is connected to your brand’s Instagram business account and is either eligible to onboard or has onboarded to Instagram’s creator marketplace as a brand.
Rate Limits
The creator marketplace APIs enforce rate limits at both the Instagram account level and the application level.
- Account-level limits: Requests are capped at 5000 per user per hour.
- Application-level limits: The number of calls an app can make within a rolling one-hour window is calculated as:
Calls per hour = 5000 * Number of Effective Users. Number of Effective Users is determined by the app’s number of unique daily active users (DAUs). If your app experiences fluctuating usage, such as higher activity on weekends and lower activity during weekdays, the calculation may use weekly or monthly active users to better reflect typical usage patterns instead.
App Review
Instructions for Developers
Your app review should clearly demonstrate how your app authenticates users and accesses data from Instagram’s creator marketplace.
1. Authentication Process
- UI (user-facing) apps:
- Before you begin recording your demo for app review, ensure that you have included the
instagram_creator_marketplace_discoverypermission in your configuration. You can access this permission by using the existing Instagram Creator Marketplace template during setup. - Show the complete, end-to-end Facebook Login flow inside your app. The login flow should match the video in the Login Flow Experience section below as closely as possible.
- Show the user connecting their Instagram account via a linked Facebook Page.
- Clearly show where the user (brand) reviews and grants consent for creator search. Your app review video should clearly show the list of permissions and ensure that “Discover content creators on the Instagram Creator Marketplace platform” is visible.
- Example screencast: How to produce a screencast for app review
- Before you begin recording your demo for app review, ensure that you have included the
- Server-to-server (S2S, no UI) apps:
- Explain your backend authentication setup (system users, tokens, permissions).
- Clearly state that your app is server-to-server in your submission.
- Confirm in the screencast that the app operates as S2S.
- If direct testing isn’t possible, provide detailed use cases and evidence supporting the S2S workflow.
2. End-to-End Permission Usage
- Explain and demonstrate how you use the
instagram_creator_marketplace_discoverypermission to discover creators. Include the specific purpose for why the app needs this functionality. - In your recorded video, demonstrate how you perform a creator search on your app UI using the Creator Marketplace Discovery API.
- Show how your app retrieves and processes creator insights, such as creator bio, follower count, and account reach.
- Explain and demonstrate how you use the
Login Flow Experience

Discovery API
The Discovery API provides personalized creator recommendations to your authenticated brand by leveraging existing data from all over Instagram, thus allowing you to discover relevant creators personalized to your brand and ad campaigns.
Instagram’s creator marketplace prioritizes creators who will perform well in your brand’s partnership ads campaigns.
Example request
curl -G \ -d 'access_token=<ACCESS_TOKEN>' \ 'https://graph.facebook.com/v25.0/<IG_USER_ID>/creator_marketplace_creators'
API Parameters
- When a creator username is specified, other filter parameters (e.g.,
creator_countries) cannot be applied. - When
similar_to_creatorsis used, keyword search (query) cannot be used. querycan be combined with other filters (e.g.,creator_age_bucket).- If the searched username (
username) matches the username of an eligible professional account, that account will be returned regardless of its creator marketplace onboarding status.
| Name | Description |
|---|---|
creator_countries | Filter creators based on their country. Input will be the country ISO code. For example: creator_countries=['US'] |
creator_min_followers | Minimum follower count for creators.
Values: 0, 10000, 25000, 50000, 75000, 100000, 250000, 1000000. |
creator_max_followers | Maximum follower count for creators.
Values: 10000, 25000, 50000, 75000, 100000, 250000, 1000000. |
creator_age_bucket | Filter creators based on their age range.
Values: 18_to_24, 25_to_34, 35_to_44, 45_to_54, 55_to_64, 65_and_above. |
creator_interests | Filter creators based on category list input.
Values: ANIMALS_AND_PETS, BOOKS_AND_LITERATURE, BUSINESS_FINANCE_AND_ECONOMICS, EDUCATION_AND_LEARNING, BEAUTY, FASHION, FITNESS_AND_WORKOUTS, FOOD_AND_DRINK, GAMES_PUZZLES_AND_PLAY, HISTORY_AND_PHILOSOPHY, HOLIDAYS_AND_CELEBRATIONS, HOME_AND_GARDEN, MUSIC_AND_AUDIO, PERFORMING_ARTS, SCIENCE_AND_TECH, SPORTS, TV_AND_MOVIES, TRAVEL_AND_LEISURE_ACTIVITIES, VEHICLES_AND_TRANSPORTATION, VISUAL_ARTS_ARCHITECTURE_AND_CRAFTS |
creator_gender | Filter creators based on their gender.
Values: male, female. |
creator_states | Filter creators based on their state or region for available countries. Input will be the state ISO code list. Requires exactly one creator_countries value. |
creator_min_engaged_accounts | Minimum engagement metric of the audience for a creator’s content.
Values: 0, 2000, 10000, 50000, 100000. |
creator_max_engaged_accounts | Maximum engagement metric of the audience for a creator’s content.
Values: 2000, 10000, 50000, 100000 |
major_audience_age_bucket | Filter creators based on their audience’s age group.
Values: 18_to_24, 25_to_34, 35_to_44, 45_to_54, 55_to_64, 65_and_above |
major_audience_gender | Filter creators based on their audience’s gender.
Values: male, female |
major_audience_countries | Filter creators based on the location of their audience. Input will be the country ISO code list. |
major_audience_states | Filter creators based on the state or region of their audience for available countries. Input will be the state ISO code list. Requires exactly one major_audience_countries value. |
query | A free-text search to find creators based on a list of keywords (e.g., username or content-related terms).
For example: to find travel-related accounts, use query=travel. |
similar_to_creators | A list of creators similar to the specified creator. Limited to only onboarded creators, input can be a list of usernames and the maximum username input is 5. |
recommendation_type | The recommendation type based on information including creative style, partnership experience, follower demographics and more for your brand. We support the following values:
|
username | The creator’s Instagram username |
custom_audience_id | ID of the custom audience (obtained from the creator_marketplace_brand_info endpoint) to filter creators whose follower base overlaps with the specified audience. |
reels_interaction_rate | The percentage of views that liked, commented, shared and saved this creator’s recent reels. This is calculated as the number of views that engaged with the reels divided by the total number of initial views. |
major_audience_device_type | Filter creators based on their audience’s primary device type. Results are filtered to only include creators whose majority audience uses the specified device type(s). Accepts an array of values.
Values: ios, android |
creator_latest_post_activity | Filter creators who recently created a public post or reel. Results are filtered to only include creators who have posted within the specified time window. Accepts a single value.
Values: last_7_days, last_30_days, last_90_days |
creator_follower_growth | Filter creators with top follower growth within the last 30 days, compared with similar creators. Results are filtered to only include creators whose follower growth ranks in the specified percentile. Accepts a single value.
Values: top_10_percent, top_30_percent, top_50_percent |
platformNew | Filter creators based on the platform they publish on. Accepts a single value, not a list. Defaults to instagram when omitted.
Values:
|
page_nameNew | Look up a creator by the name of their Facebook Page. This is a name search rather than an exact Page lookup, and it returns the single best match rather than a ranked list. If you pass both page_name and username, username takes precedence and page_name is ignored. |
creator_languageNew | Filter creators based on the language they are predicted to create in. Input will be a list of ISO 639-1 language codes. Maximum of 10 values. |
has_portfolioNew | Filter creators based on whether they have published a portfolio.
Values: true, false |
has_public_contact_emailNew | Filter creators based on whether they offer a public contact email on their profile.
Values: true, false |
exclude_messaged_creatorsNew | Exclude creators your brand has already messaged.
Values: true, false |
verified_accountNew | Filter creators based on whether their Instagram account is verified.
Values: true, false |
featured_in_paid_adsNew | Filter creators based on whether they have been featured in paid ads.
Values: true, false |
Response fields
A search returns creators on Instagram unless you ask for Facebook creators. Without the
platform parameter, every result is an Instagram creator, so only the Instagram creator column applies. Pass platform to include creators on Facebook.| Name | Description | Instagram creator | Facebook creator New |
|---|---|---|---|
username | The Instagram handle or username of the creator. Use page_name when you need a display name for a Facebook creator. | Yes | No |
is_account_verified | Indicates whether the creator’s Instagram account is verified. | Yes | Yes |
biography | The bio or description provided by the creator on their Instagram profile. | Yes | Yes |
country | The country in which the creator is based. | Yes | Yes |
gender | The gender of the creator (only available for onboarded creators). | Yes | Yes |
age_bucket | The age range or bucket to which the creator belongs, only available for onboarded creators. 18-24, 25-34. | Yes | Yes |
insights | Metric insights of a creator, such as account_engaged_count:30 | Yes | Yes, for a subset of metrics |
onboarded_status | Whether a creator has been onboarded to the creator marketplace. | Yes | Yes |
id | Instagram ID For a creator who is only on Facebook this is an app-scoped Facebook user ID, not an Instagram ID. | Yes | Yes |
email | Creator’s email, if available | Yes | Yes |
badges | The badges of the creator. Supported values include:
| Yes | Yes |
portfolio_url | Creator’s portfolio URL, if available | Yes | Yes |
profile_picture_url | The URL of the creator’s profile picture, if available. | Yes | Yes |
has_brand_partnership_experience | Whether the creator has branded content or partnership ads collaboration experience in the past year. For this field to return values, username has to be specified in the API call. | Yes | No |
past_brand_partnership_partners | The brands the creator has collaborated with on branded content or partnership ads in the past year. For this field to return values, username has to be specified in the API call. | Yes | No |
branded_content_media | Returns the 30 most recent branded content organic media of a particular creator. See insights section for supported fields. For this field to return values, username has to be specified in the API call. | Yes | Yes |
recent_media | Returns the top 30 recent media of a particular creator. See insights section for supported fields. For this field to return values, username has to be specified in the API call. | Yes | Yes |
past_partnership_ads_media | Returns media where this creator has partnered with advertisers to co-create ads. Only includes partnership ads that have been active within the past year. For this field to return values, username has to be specified in the API call.Note: Insights are not available for past_partnership_ads_media. | Yes | Yes |
platformsNew | The platforms where this creator has content that the creator marketplace can surface. An array of strings. Values: ["instagram"], ["facebook"], ["instagram", "facebook"] | Yes | Yes |
page_idNew | The ID of the creator’s Facebook Page. | No | Yes |
page_nameNew | The name of the creator’s Facebook Page. | No | Yes |
categoryNew | The category the creator has selected for their professional account, if available. | Yes | Yes |
is_brand_following_creatorNew | Indicates whether your brand follows the creator on Instagram. | Yes | No |
is_creator_following_brandNew | Indicates whether the creator follows your brand on Instagram. | Yes | No |
Example request
curl -G \ -d 'creator_countries=["US"]' \ -d 'fields=id,username,country,gender' \ -d 'access_token=<ACCESS_TOKEN>' \ 'https://graph.facebook.com/v25.0/<IG_USER_ID>/creator_marketplace_creators'
Example response
{ "data": [ { "id": "178414869381437360", "username": "xxx", "country": "BR", "gender": "female" }, { "id": "178414965628223823", "username": "xxx", "country": "IN", "gender": "male" } ] }
Example request: search across both platforms
curl -G \ -d 'platform=any' \ -d 'creator_countries=["US"]' \ -d 'fields=id,username,page_id,page_name,platforms' \ -d 'access_token=<ACCESS_TOKEN>' \ 'https://graph.facebook.com/v25.0/<IG_USER_ID>/creator_marketplace_creators'
Example response
{ "data": [ { "id": "17841486938143736", "username": "xxx", "platforms": ["instagram"] }, { "id": "10465259075662", "page_id": "104965259075662", "page_name": "Example Page", "platforms": ["facebook"] }, { "id": "17841496562822382", "username": "yyy", "page_id": "112233445566778", "page_name": "Another Example Page", "platforms": ["instagram", "facebook"] } ] }
The first creator has no
page_id or page_name, and the second has no username. Both are expected. Use platforms to decide which fields to read.Example request: look up a creator by Facebook Page name
curl -G \ -d 'page_name=Example Page' \ -d 'fields=id,username,page_id,page_name,platforms' \ -d 'access_token=<ACCESS_TOKEN>' \ 'https://graph.facebook.com/v25.0/<IG_USER_ID>/creator_marketplace_creators'
Error codes
| Error Code | Description |
|---|---|
10 Permission Denied
App Missing Permission
| The app lacks the required instagram_creator_marketplace_discovery permission. |
10 Permission Denied | Brand Eligibility
The brand is not eligible to onboard to the creator marketplace, so the API call cannot be made.
|
100 Invalid Parameter Input | General message for invalid API parameter inputs (e.g., account follower count minimum bound exceeds the upper bound, category exceeds the limit of 5). |
| Error Code | Description |
|---|---|
100 Invalid Parameter Input
No creator matched `page_name`
| No creator in the creator marketplace matched the name passed in page_name. The Page may not exist, or it may exist without being onboarded to the creator marketplace. |
Creator Insights API
The Creator Insights API allows you to access performance metrics for individual creators, including follower counts, audience engagement, and reach data. Use the
username parameter to query insights for a specific creator.Creator Insights Metrics
The following metrics are available when querying creator insights. Each metric supports specific time periods, ranges, and granularity breakdowns.
Not every metric is available for both kinds of creator. Requesting a metric for a creator on a platform that does not support it returns error code
100.total_views and account_interactions support their breakdowns only with period(overall). Combining a breakdown with period(day) on either metric returns error code 100. Neither metric supports the lifetime time range.| Metric | Supported Periods | Supported Time Range | Supported Granularity | Instagram creator | Facebook creator New |
|---|---|---|---|---|---|
total_followers | Overall | Lifetime | NA | Yes | Yes |
creator_engaged_accounts | Day, Overall | this_week, last_14_days, this_month | follow_type, gender, age, top_countries, top_cities | Yes | No |
creator_reach | Day, Overall | this_week, last_14_days, this_month | follow_type, media_type | Yes | No |
reels_interaction_rate | Overall | last_90_days | NA | Yes | Yes |
reels_hook_rate | Overall | last_90_days | NA | Yes | Yes |
total_viewsNew | Day, Overall | this_week, last_14_days, this_month | follow_type, media_type | Yes | Yes |
account_interactionsNew | Day, Overall | this_week, last_14_days, this_month | follow_type, media_type | Yes | Yes |
Example request
curl -G \ -d 'username=<CREATOR_USERNAME>' \ -d 'fields=insights.metrics(creator_reach).breakdown(follow_type)' \ -d 'access_token=<ACCESS_TOKEN>' \ 'https://graph.facebook.com/v25.0/<IG_USER_ID>/creator_marketplace_creators'
Cross-platform creator insights
Add
.platform() to the insights field to choose which platforms a metric is resolved against. Unlike the platform parameter on the Discovery API, .platform() accepts more than one value.curl -G \ -d 'username=<CREATOR_USERNAME>' \ -d 'fields=insights.metrics(total_views).period(overall).time_range(last_14_days).platform(instagram,facebook)' \ -d 'access_token=<ACCESS_TOKEN>' \ 'https://graph.facebook.com/v25.0/<IG_USER_ID>/creator_marketplace_creators'
Each requested platform returns its own entry, tagged with a
platform key:{ "insights": { "data": [ { "name": "total_views", "platform": "instagram", "period": "overall", "time_range": "last_14_days", "total_value": { "value": 404042 } }, { "name": "total_views", "platform": "facebook", "period": "overall", "time_range": "last_14_days", "total_value": { "value": 321 } } ] } }
Values are never combined across platforms. There is no cross-platform total, so add the per-platform values yourself if you need one.
If you omit
.platform(), the response keeps its current shape: Instagram data only, with no platform key on each entry. Requesting a metric on a platform that does not support it returns error code 100.Media Insights Metrics
A media edge returns Instagram media unless you ask for Facebook media. Without
.platform() on recent_media, every item is Instagram media, so only the Instagram media column applies. The insights field on a media item accepts .platform() as well, and all four media metrics, likes, comments, views, and shares, are supported on both platforms.A creator’s media list can mix Instagram and Facebook items. Read the
platform field on each media item to decide which permalink and type fields to use, rather than reading the creator’s platforms field.| Name | Description | Instagram media | Facebook media New |
|---|---|---|---|
id | Media id of the content Example: 17841463918802342 | Yes | Yes |
product_type | The media product type Example: Reels | Yes | No |
media_type | The media type Example: Image | Yes | No |
permalink | The permalink of the media Example: https://www.instagram.com/reel/C_Tlbb-sGMi/ | Yes | No |
thumbnail_url | The thumbnail URL of the media Example: https://scontent-sjc3-1.cdninstagram.com/v/t...6A251557 | Yes | No |
creation_time | The time the media was created Example: 2024-08-30T19:36:26+0000 | Yes | Yes |
caption | The caption of the media Example: Test Caption | Yes | Yes |
tagged_brand | The brand that the organic media has been paid to partner with. If the media is not a branded content with partnership, the field will not be returned. Example: instagram | Yes | Yes |
likes | Total number of likes the media receives. Example: 1000 | Yes | Yes |
comments | Total number of comments the media receives. Example: 500 | Yes | Yes |
views | Total number of views on the media (only available for video media). Example: 30000 | Yes | Yes |
shares | Total number of shares the media gets. Example: 800 | Yes | Yes |
platformNew | The platforms the media was published on. An array of strings. Example: ["facebook"] | Yes | Yes |
facebook_post_idNew | The ID of the media on Facebook. Example: 98909889290 | No | Yes |
facebook_permalinkNew | The permalink of the media on Facebook. Example: https://www.facebook.com/reel/C_Tlbb-sGMi/ | No | Yes |
Example request
curl -G \ -d 'username=<CREATOR_USERNAME>' \ -d 'fields=branded_content_media{media_type,insights.metrics(views)},recent_media{media_type,insights.metrics(views)}' \ -d 'access_token=<ACCESS_TOKEN>' \ 'https://graph.facebook.com/v25.0/<IG_USER_ID>/creator_marketplace_creators'
Cross-platform media
The
recent_media edge accepts .platform(), which selects the platforms the media is drawn from. It accepts more than one value.curl -G \ -d 'username=<CREATOR_USERNAME>' \ -d 'fields=recent_media.platform(instagram,facebook).limit(30){id,platform,media_type,product_type,caption,creation_time,permalink,facebook_post_id,facebook_permalink}' \ -d 'access_token=<ACCESS_TOKEN>' \ 'https://graph.facebook.com/v25.0/<IG_USER_ID>/creator_marketplace_creators'
Cross-platform media insights
curl -G \ -d 'username=<CREATOR_USERNAME>' \ -d 'fields=recent_media.platform(instagram,facebook){id,platform,insights.metrics(views,likes,comments,shares).platform(instagram,facebook){name,platform,total_value{value}}}' \ -d 'access_token=<ACCESS_TOKEN>' \ 'https://graph.facebook.com/v25.0/<IG_USER_ID>/creator_marketplace_creators'
As with creator insights, each metric returns one entry per requested platform, tagged with a
platform key:{ "id": "17886595920559627", "platform": ["instagram"], "insights": { "data": [ { "name": "views", "platform": "instagram", "total_value": { "value": 2220 } }, { "name": "views", "platform": "facebook", "total_value": { "value": 340 } } ] } }
Error codes
| Error Code | Description |
|---|---|
100 Invalid Parameter Input | General message for invalid API parameter inputs (e.g., the input period is not supported by the provided metrics). |
Creator Marketplace Brand Information API
The Creator Marketplace Brand Information API allows brands and agencies to retrieve custom audiences that are eligible for creator discovery filtering. This is the first step in the Custom Audience-based discovery workflow — call this endpoint to list available audiences, then pass the selected
custom_audience_id to the discovery API to filter creators.Permissions
To use this API, permissions must be granted using Facebook Login. These permissions are required to access the creator marketplace brand information API:
instagram_creator_marketplace_discoveryinstagram_basicads_management
Example request
curl -G \ -d 'access_token=<ACCESS_TOKEN>' \ 'https://graph.facebook.com/v25.0/<IG_USER_ID>/creator_marketplace_brand_info'
API Parameters
| Name | Description |
|---|---|
acting_business_id | The agency Business ID when accessing on behalf of a client. Required for agencies to see custom audiences from ad accounts shared via Business Suite. Without this parameter, only audiences from the IG user’s directly owned ad accounts are returned. |
Response fields
| Name | Description |
|---|---|
custom_audiences_access_status | Indicates whether the brand has access to custom audiences for creator filtering. |
custom_audiences | List of custom audiences available for creator filtering. |
id | The unique ID of the custom audience. Pass this value as custom_audience_id to the creator_marketplace_creators endpoint. |
name | The display name of the custom audience. |
Example request
curl -G \ -d 'acting_business_id=123456' \ -d 'access_token=<ACCESS_TOKEN>' \ 'https://graph.facebook.com/v25.0/<IG_USER_ID>/creator_marketplace_brand_info'
Example response
{ "custom_audiences_access_status": "HAS_ACCESS", "custom_audiences": [ { "id": "12354465435359", "name": "High Value Customers Q1" }, { "id": "5645451351544564", "name": "Website Visitors 30d" } ] }
Error codes
| Error Code | Description |
|---|---|
10 Authorization Error | The app lacks the required ads_management permission against the targeted ad account. |
100 Invalid Parameter Input | The acting_business_id does not have access to the specified IG user’s ad accounts. |
Learn More
- App Review process
- Facebook Login