GET /creators/{id}: One creator's full profile

Overview

Scope: creators:read. One creator by the id a GET /creators row carries (a UUID), at /api/v1/creators/{id}. There is no lookup by X handle: no creator read carries a handle or an x.com link (the handle shows on a paid plan's quote), and this profile is opened by id only. MCP tool: creator_get.

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

Parameters

Parameters of GET /creators/{id}
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The creator's id from a GET /creators row (a UUID).
`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.

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/$CREATOR_ID" \
  -H "Authorization: Bearer $DISTRIBUTION_API_KEY"

Response

200 OK. The body has these fields:

Response fields of GET /creators/{id}
Name	Type	Required	Description
`id`	string (uuid)	No
`handle`	string or null	No	Null in every creator read: a creator is named before payment, and its X handle shows once the brand's order for a plan with that creator is paid, on that plan's quote (plan_quote).
`name`	string or null	No
`url`	string or null	No	Null in every creator read, as handle: the X profile link shows on the paid plan's quote.
`status`	one of "approved", "borderline", "not_reviewed", "declined"	No
`status_label`	string	No
`status_reason`	string	No
`in_automatic_plans`	boolean	No
`match_score`	integer or null	No
`match_label`	string or null	No
`on_sale`	boolean	No
`reach_band`	one of "nano", "micro", "mid", "macro", "mega"	No	The creator's size by followers, smallest to largest.
`median_views_30d`	integer or null	No	Deprecated: the same number as median_views_30d_network. Removed on 2027-01-11; read median_views_30d_network.
`median_views_30d_network`	integer or null	No	Median views per post over the creator's last 30 days, as the network measures it across all their posts. Prices, expected views and format advice use this number. It can differ from posts_summary.posts_sample_median_views, which covers only the posts we hold.
`followers`	integer or null	No	X followers, as the network last measured them. Null when not measured.
`verified_badge`	boolean or null	No	Whether the account carries the X blue check. Null when unknown.
`country`	string or null	No	The country or region X shows on the account's About panel. Null when X shows none; never inferred.
`language`	string or null	No	The language the creator posts in, as a name (for example English). Null when unknown.
`segments`	array of string	No
`bio`	string or null	No
`positioning`	string or null	No	One line on who the creator is, taken from their own bio (never written by us); null when the bio has none.
`avatar_url`	string or null	No
`ask_price`	boolean	No	true when nothing is on sale for this creator: the action is Ask for a price (creator_ask_price, POST /creators/{id}/price-request), which asks our team, never the creator; price_estimate is an estimate, never a price. false when a format is on sale: add it from offerings with plan_add_creator.
`price_estimate`	object or null	No	For a creator with nothing on sale: an estimated price range from its metrics (the ERP's suggested budget band), never a price; null when it has a price. Ask for a price (creator_ask_price, POST /creators/{id}/price-request) asks our team for a real one; the creator is never contacted directly.
`engagement_rate_30d`	number or null	No
`posts_per_week`	number or null	No
`match_reasons`	array of object	No	Why this creator (row 7858), each from a number the network holds: topic (the brand's segments the creator posts about; a topic match, not audience overlap), reach (median views a post over 30 days, with its as-of date), past_launches (launches posted about), engagement (only when above the median of the creators listed). Empty when none can be said; never a price.
`past_collabs`	array of object	No	Launches the creator posted or quoted among the launches the network tracks, newest first (at most 12), then detected paid partnerships. An empty list means none was found in the launches we track, not that the creator never worked with a brand.
`recent_posts`	array of object	No	The creator's own posts with their numbers, newest first: up to 30 from the last 30 days for an approved creator.
`posts_summary`	object or null	No	posts_sample_median_views is the median over the posts in recent_posts only (at most 30 held posts), so it can differ from median_views_30d_network, which covers all the creator's posts. Counted from recent_posts: null unless 3 or more dated posts fall in the 30 days up to as_of. A summary of their posts; top_post.excerpt quotes the creator's own post.
`offerings`	array of object	No
`synced_at`	string (date-time) or null	No	When the creator's profile and posts were last synced (ISO 8601). Null when unknown.
`refresh_failed_at`	string (date-time) or null	No	When the last nightly refresh of this creator failed (ISO 8601); null when the last refresh worked or none has run. The figures then stay as of synced_at.
`advice`	object	No

200 response body, every field with its type

{
  "id": "<uuid>",
  "handle": "<string>",
  "name": "<string>",
  "url": "<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",
      "url": "<string>",
      "brand": {
        "handle": "<string>",
        "avatar_url": "<string>",
        "site": "<string>",
        "initials": "<string>"
      }
    }
  ],
  "recent_posts": [
    {}
  ],
  "posts_summary": {
    "posts": 0,
    "window_days": 0,
    "capped": false,
    "median_views": 0,
    "posts_sample_median_views": 0,
    "top_post": {
      "url": "<string>",
      "views": 0,
      "excerpt": "<string>"
    },
    "recurring": [
      "<string>"
    ],
    "latest_at": "<date-time>",
    "as_of": "<date-time>"
  },
  "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>"
  }
}

Errors

Error statuses of GET /creators/{id}
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.
`404`	No approved creator has that id.
`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. 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: Approved creators on sale now, by name, with price per format and format advice
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.