GET /creators: Approved creators on sale now, by name, with price per format and format advice

Overview

Scope: creators:read.

Endpoint: GET https://app.distribution.tech/api/v1/creators
Scope: creators:read
Changes data: No, a read
MCP tool: creators_search

Parameters

Parameters of GET /creators
Name	In	Type	Required	Description
`q`	query	string	No	Part of a name, handle or bio.
`segment`	query	string	No	An audience segment id, e.g. ai or saas_b2b.
`reach_band`	query	one of "nano", "micro", "mid", "macro", "mega"	No	The creator's size by followers.
`goal`	query	one of "launch", "funding", "feature", "program"	No	The campaign's goal: launch, funding or feature (an announcement with a post of yours to quote) or program (steady reach). Shapes the format advice.
`match`	query	string	No	Your audience segments, comma separated (from /audience): adds match_score (over 70 strong, over 50 good) and ranks by it.
`limit`	query	integer	No	Page size: default 24, at most 50.
`offset`	query	integer	No	Where the page starts; page through every approved creator with total.
`fit`	query	boolean	No	true: only creators reaching at least one of the match segments (the 'fit your audience' set); total then counts only those.
`country`	query	string	No	The creator's country as X reports it, exact and case-insensitive, e.g. United States.
`language`	query	string	No	The language the creator posts in, exact and case-insensitive, e.g. English.
`followers_min`	query	integer	No	At least this many X followers.
`followers_max`	query	integer	No	At most this many X followers.
`er_min`	query	number	No	At least this engagement rate over the last 30 days, in percent (0 to 100, two decimals).
`match_min`	query	integer	No	At least this match score (0 to 100; over 70 strong, over 50 good). Needs match.
`format`	query	one of "post", "quote", "thread"	No	Only creators selling this format; price and price filters then read that format's price.
`price_min`	query	integer	No	The cheapest all-in price (of the format, when one is given) is at least this many US dollars.
`price_max`	query	integer	No	The cheapest all-in price (of the format, when one is given) is at most this many US dollars.
`sort`	query	one of "match", "followers", "engagement", "views", "price"	No	Order: match (default, best fit first), followers, engagement, views (median views a post) or price (cheapest all-in price).
`dir`	query	one of "desc", "asc"	No	desc (default) or asc.
`budget`	query	integer	No	The campaign budget in US dollars. It sizes the shortlist (three times the posts it buys at the good fits' median price, 10 to 50); without it the list is 25. It never filters.

Request with curl

Set DISTRIBUTION_API_KEY to a key from Developers with the creators:read scope, and each path variable to an id from an earlier answer. The body carries the required fields.

curl

curl "https://app.distribution.tech/api/v1/creators" \
  -H "Authorization: Bearer $DISTRIBUTION_API_KEY"

Response

200 OK. The body has these fields:

Response fields of GET /creators
Name	Type	Required	Description
`total`	integer	No	How many creators this answer lists: the shortlist, never a count of the network.
`priced`	integer	No	How many of total are bookable now by the one rule in the API description (What bookable means); the rest carry price_estimate, never a price.
`catalog`	object	No	The whole network, whatever this call filtered: the same counts as the app and the site (GET /api/network/facts on the app host), refreshed at most every five minutes. Left out when the network cannot be counted right now, never guessed.
`cap`	integer	No	How many creators the selection holds (the same as total).
`limit`	integer	No	This page's size: default 24, at most 50.
`offset`	integer	No	Where this page starts, at most total (an offset past the end is answered as total); the next page starts at offset + limit while it is below total.
`creators`	array of object	No	Summary rows, best fits first by score and in the order asked for: no handle, link or posts. GET /creators/{id} (creator_get) opens one in full.

200 response body, every field with its type

{
  "total": 0,
  "priced": 0,
  "catalog": {
    "approved": 0,
    "priced": 0
  },
  "cap": 0,
  "limit": 0,
  "offset": 0,
  "creators": [
    {
      "provenance": {
        "followers": {
          "source": "<string>",
          "method": "<string>",
          "measured_at": "<string>",
          "expires_at": "<string>",
          "label": "Verified",
          "stale": false,
          "as_of": "<string>"
        },
        "median_views_30d": {
          "source": "<string>",
          "method": "<string>",
          "measured_at": "<string>",
          "expires_at": "<string>",
          "label": "Verified",
          "stale": false,
          "as_of": "<string>"
        },
        "engagement_rate_30d": {
          "source": "<string>",
          "method": "<string>",
          "measured_at": "<string>",
          "expires_at": "<string>",
          "label": "Verified",
          "stale": false,
          "as_of": "<string>"
        }
      },
      "id": "<uuid>",
      "name": "<string>",
      "status": "approved",
      "status_label": "<string>",
      "status_reason": "<string>",
      "in_automatic_plans": false,
      "match_score": 0,
      "match_label": "<string>",
      "on_sale": false,
      "reach_band": "nano",
      "median_views_30d": 0,
      "median_views_30d_network": 0,
      "followers": 0,
      "verified_badge": false,
      "country": "<string>",
      "language": "<string>",
      "segments": [
        "<string>"
      ],
      "bio": "<string>",
      "positioning": "<string>",
      "avatar_url": "<string>",
      "ask_price": false,
      "price_estimate": {
        "min_usd": 0,
        "max_usd": 0,
        "label": "<string>",
        "provenance": {
          "source": "<string>",
          "method": "<string>",
          "measured_at": "<string>",
          "expires_at": "<string>",
          "label": "Verified",
          "stale": false,
          "as_of": "<string>"
        },
        "calc": {
          "calc_version": "<string>",
          "inputs": {}
        }
      },
      "engagement_rate_30d": 0,
      "posts_per_week": 0,
      "match_reasons": [
        {
          "kind": "topic",
          "text": "<string>"
        }
      ],
      "past_collabs": [
        {
          "project": "<string>",
          "title": "<string>",
          "date": "<date>",
          "role": "Launch post",
          "brand": {
            "avatar_url": "<string>",
            "site": "<string>",
            "initials": "<string>"
          }
        }
      ],
      "offerings": [
        {
          "unit_id": "<uuid>",
          "format": "post",
          "label": "<string>",
          "deliverable": "<string>",
          "price_cents": 0,
          "buyable": false,
          "price_as_of": "<date>",
          "expected_views": 0,
          "cost_per_1k_views_cents": 0,
          "provenance": {
            "source": "<string>",
            "method": "<string>",
            "measured_at": "<string>",
            "expires_at": "<string>",
            "label": "Verified",
            "stale": false,
            "as_of": "<string>"
          },
          "calc": {
            "calc_version": "<string>",
            "inputs": {}
          }
        }
      ],
      "synced_at": "<date-time>",
      "refresh_failed_at": "<date-time>",
      "advice": {
        "recommended": "post",
        "reason": "<string>"
      },
      "views_series": [
        0
      ]
    }
  ]
}

Errors

Error statuses of GET /creators
Status	When
`400`	A parameter is not valid: details.problems names each field and what it accepts.
`401`	No API key, an unknown one, or a revoked one.
`403`	The key does not have this endpoint's scope.
`429`	Too many requests for this key in the current minute (60); Retry-After and RateLimit-Reset say when to try again. On POST /campaigns and on POST /plans/current/lines when it starts a plan: the brand's 3 new campaigns in 24 hours are used (details.reason daily_campaign_limit); details.resets_at and Retry-After say when the limit reopens, a rolling 24 hours from the first of them, not a calendar day; archiving or deleting a campaign does not give its slot back. On GET /creators and GET /creators/{id}: a creator read limit is used (details.reason per_minute, daily_lists, daily_reveals, daily_seen or locked). daily_seen is your workspace's one pool of 300 creator views a day (300 different creators shown or opened since midnight UTC), shared by the app and every API key of the brand: details.scope workspace and details.limit 300; a creator already seen today, in the app or through any key, still opens and costs nothing. daily_lists is the day's list calls (each GET /creators page or creators_search is one; details.limit, 60): it is counted apart from creator views, resets at midnight UTC, and Retry-After says when. daily_reveals is the day's creator profiles opened (details.limit, 60). The other reasons are this key's own limit (details.scope key) or the brand's ceiling over all its keys (details.scope api).
`500`	internal: the request failed on our side. Try again.
`503`	unavailable: the service or this part of it is not reachable right now. Try again shortly.

GET /creators/{id}: One creator's full profile
POST /creators/{id}/price-request: Ask for a price

Get access

Keys are created in Developers once your brand is approved. Connect an agent to ask for access, then read the agent guide for the full flow.