Instagram Platform

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_discovery
  • instagram_basic
  • pages_manage_metadata
  • pages_show_list
  • business_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_discovery permission 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
  • 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

      1. Explain and demonstrate how you use the instagram_creator_marketplace_discovery permission to discover creators. Include the specific purpose for why the app needs this functionality.
      2. In your recorded video, demonstrate how you perform a creator search on your app UI using the Creator Marketplace Discovery API.
      3. Show how your app retrieves and processes creator insights, such as creator bio, follower count, and account reach.

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_creators is used, keyword search (query) cannot be used.
  • query can 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:
  • most_relevant_for_me: Return creators most relevant for you.
  • high_ad_performance: Return creators who are expected to deliver high ad performance for you.
  • most_ads_experience: Return creators with the most ads experience.
  • similar_brands: Return creators who’ve partnered with brands like you.
  • similar_audience: Return creators similar to creators you’ve worked with before.
  • interested_in_collaboration: Return creators who are interested in collaborating with you.
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
platform
New
Filter creators based on the platform they publish on. Accepts a single value, not a list. Defaults to instagram when omitted. Values:
  • instagram: Creators on Instagram. They may also be on Facebook.
  • facebook: Creators on Facebook. They may also be on Instagram.
  • both: Only creators who are on Instagram and Facebook, with the two accounts linked.
  • any: Creators on either platform.
page_name
New
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_language
New
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_portfolio
New
Filter creators based on whether they have published a portfolio. Values:true, false
has_public_contact_email
New
Filter creators based on whether they offer a public contact email on their profile. Values:true, false
exclude_messaged_creators
New
Exclude creators your brand has already messaged. Values:true, false
verified_account
New
Filter creators based on whether their Instagram account is verified. Values:true, false
featured_in_paid_ads
New
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:
  • Partnership ads: This creator has experience with partnership ads.
  • Branded content: This creator has experience with branded content.
  • Strong hooks: Users frequently view this creator’s content past the first 3 seconds.
  • Engaging reels: Users like, comment and share this creator’s reels per view more often than similar creators’ reels.
  • Responsive: This creator typically responds within 48 hours.
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
platforms
New
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_id
New
The ID of the creator’s Facebook Page.
No
Yes
page_name
New
The name of the creator’s Facebook Page.
No
Yes
category
New
The category the creator has selected for their professional account, if available.
Yes
Yes
is_brand_following_creator
New
Indicates whether your brand follows the creator on Instagram.
Yes
No
is_creator_following_brand
New
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_views
New
Day, Overall
this_week, last_14_days, this_month
follow_type, media_type
Yes
Yes
account_interactions
New
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
platform
New
The platforms the media was published on. An array of strings.
Example: ["facebook"]
Yes
Yes
facebook_post_id
New
The ID of the media on Facebook.
Example: 98909889290
No
Yes
facebook_permalink
New
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_discovery
  • instagram_basic
  • ads_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