curl --request POST \
  --url https://external-api.streamforge.com/creator-requests \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "platform": "youtube",
  "handle": "@examplecreator"
}
'

{
  "payload": {
    "request_id": "cr_3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
    "status": "partial",
    "stage": "done",
    "progress": 100,
    "message": "The profile is ready; the audience analysis is not available",
    "platform": "twitch",
    "handle": "streamer123",
    "profile_id": "484563826",
    "parts": {
      "profile": "ready",
      "audience": "insufficient_data"
    },
    "audience_reason": "There is not enough public audience data for this creator to produce an analysis.",
    "poll_after_seconds": null,
    "status_url": "/creator-requests/cr_3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
    "result": {
      "profile": {
        "platform": "twitch",
        "profile_id": "484563826",
        "name": "streamer123",
        "display_name": "Streamer 123",
        "url": "https://twitch.tv/streamer123"
      },
      "audience": null,
      "audience_updated_at": null
    }
  },
  "meta": {
    "received_at": "2026-10-13T12:00:00.000Z",
    "credits_charged": 1
  }
}

{
  "payload": {
    "request_id": "cr_3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
    "status": "pending",
    "stage": "queued",
    "progress": 0,
    "message": "Queued",
    "platform": "youtube",
    "handle": "examplecreator",
    "profile_id": null,
    "parts": {
      "profile": "pending",
      "audience": "pending"
    },
    "audience_reason": null,
    "poll_after_seconds": 3,
    "status_url": "/creator-requests/cr_3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
    "result": null
  },
  "meta": {
    "received_at": "2026-10-13T12:00:00.000Z",
    "credits_charged": 1
  }
}

{
  "error": {
    "message": "That is not a supported creator profile URL. Use a link to a creator profile or channel on YouTube, Twitch, TikTok, Instagram or X.",
    "status": 400,
    "code": "unsupported_profile_url"
  },
  "meta": {
    "request_id": "5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4"
  }
}

{
  "error": {
    "status": 401,
    "message": "API key is required"
  },
  "meta": {
    "request_id": "5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4"
  }
}

{
  "error": {
    "message": "Credits exceeded",
    "status": 403,
    "code": "credits_exceeded"
  },
  "meta": {
    "request_id": "5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4"
  }
}

{
  "error": {
    "message": "Rate limit exceeded",
    "status": 429
  },
  "meta": {
    "request_id": "5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4"
  }
}

{
  "error": {
    "message": "This creator cannot be prepared right now. Try again shortly.",
    "status": 503,
    "code": "preparation_unavailable"
  },
  "meta": {
    "request_id": "5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4"
  }
}

Creator requests

Request a creator

Ask Streamforge to prepare a creator: fetch the profile and, unless you opt out with audience: false, produce the audience analysis. Use it for a creator the profile endpoints answer 404 for, or one that has a profile but no audience analysis yet.

Identify the creator in one of three ways: platform with handle, platform with profile_id, or a profile url on its own. A link that is not a creator profile, such as a video, a post or a search page, is rejected with unsupported_profile_url rather than guessed at.

The request is asynchronous:

If everything you asked for can already be served, the answer is 200 and the data is in result.
Otherwise the answer is 202, with the request’s address in the Location header. Read GET /creator-requests/{request_id} after Retry-After seconds, and again until it answers 200.

pending and processing mean the request is in progress. A finished request has one of four statuses:

Status	Meaning
`ready`	The profile is in `result`, and so is the audience analysis if you asked for it
`partial`	The profile is in `result`; the audience analysis is not. `parts.audience` and `audience_reason` say why
`not_found`	There is no such creator on that platform
`failed`	The request could not be completed. You can request the creator again

partial is an ordinary outcome, not an error. An audience analysis is not always possible: there may not be enough public audience data for the creator (insufficient_data), it may not be available for the creator’s platform (unsupported), the daily capacity for new analyses may be used up (unavailable, in which case request the creator again after the daily reset), or the analysis itself may not complete (failed).

result.profile is filled in as soon as the profile can be served, which can be while the audience analysis is still in progress.

Credits: an accepted request (200 or 202) costs 1 credit, once. Sending the same request again while it is in progress returns that request and costs nothing. The credit is returned if the request ends not_found or failed. meta.credits_charged is what the request has cost in total and the X-Credits-request-cost header is what this call cost, both in credits.

Available with a Streamforge API key only.

POST

creator-requests

curl --request POST \
  --url https://external-api.streamforge.com/creator-requests \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "platform": "youtube",
  "handle": "@examplecreator"
}
'

{
  "payload": {
    "request_id": "cr_3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
    "status": "partial",
    "stage": "done",
    "progress": 100,
    "message": "The profile is ready; the audience analysis is not available",
    "platform": "twitch",
    "handle": "streamer123",
    "profile_id": "484563826",
    "parts": {
      "profile": "ready",
      "audience": "insufficient_data"
    },
    "audience_reason": "There is not enough public audience data for this creator to produce an analysis.",
    "poll_after_seconds": null,
    "status_url": "/creator-requests/cr_3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
    "result": {
      "profile": {
        "platform": "twitch",
        "profile_id": "484563826",
        "name": "streamer123",
        "display_name": "Streamer 123",
        "url": "https://twitch.tv/streamer123"
      },
      "audience": null,
      "audience_updated_at": null
    }
  },
  "meta": {
    "received_at": "2026-10-13T12:00:00.000Z",
    "credits_charged": 1
  }
}

{
  "payload": {
    "request_id": "cr_3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
    "status": "pending",
    "stage": "queued",
    "progress": 0,
    "message": "Queued",
    "platform": "youtube",
    "handle": "examplecreator",
    "profile_id": null,
    "parts": {
      "profile": "pending",
      "audience": "pending"
    },
    "audience_reason": null,
    "poll_after_seconds": 3,
    "status_url": "/creator-requests/cr_3f9a1c2b4d5e6f708192a3b4c5d6e7f8",
    "result": null
  },
  "meta": {
    "received_at": "2026-10-13T12:00:00.000Z",
    "credits_charged": 1
  }
}

{
  "error": {
    "message": "That is not a supported creator profile URL. Use a link to a creator profile or channel on YouTube, Twitch, TikTok, Instagram or X.",
    "status": 400,
    "code": "unsupported_profile_url"
  },
  "meta": {
    "request_id": "5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4"
  }
}

{
  "error": {
    "status": 401,
    "message": "API key is required"
  },
  "meta": {
    "request_id": "5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4"
  }
}

{
  "error": {
    "message": "Credits exceeded",
    "status": 403,
    "code": "credits_exceeded"
  },
  "meta": {
    "request_id": "5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4"
  }
}

{
  "error": {
    "message": "Rate limit exceeded",
    "status": 429
  },
  "meta": {
    "request_id": "5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4"
  }
}

{
  "error": {
    "message": "This creator cannot be prepared right now. Try again shortly.",
    "status": 503,
    "code": "preparation_unavailable"
  },
  "meta": {
    "request_id": "5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4"
  }
}

Authorizations

x-api-key

string

header

required

Your API key. Include it in the x-api-key header for all requests.

Headers

x-streamforge-end-user

string

Only for API keys that carry a per-end-user allowance, which must send it on every call; other keys can leave it out. An opaque identifier for the person the request is made for: 8 to 128 characters of A-Z, a-z, 0-9, _ and -. Send a stable pseudonymous value, not an IP address or other personal data. A request can be read back only with the value it was created with.

Pattern: ^[A-Za-z0-9_-]{8,128}$

Example:

"8f2c1d7ab0e94c53"

Body

application/json

Exactly one of handle, profile_id and url. platform is required with handle or profile_id; with url it is optional and, if sent, must be the platform the URL belongs to.

platform

enum<string>

Available options:

twitch,

youtube,

instagram,

tiktok,

twitter

handle

string

The creator's handle on the platform. Case does not matter and a leading @ is ignored

Example:

"examplecreator"

profile_id

string

Platform-specific creator ID. For YouTube, a channel ID (UC followed by 22 characters)

Example:

"484563826"

url

string

A link to the creator's profile or channel on YouTube, Twitch, TikTok, Instagram or X. The scheme is optional

Example:

"https://www.youtube.com/@examplecreator"

audience

boolean

default:true

Whether to produce the audience analysis as well as the profile

Response

The request has finished. payload.status is ready, partial, not_found or failed

payload

object

Show child attributes

Health

Profiles

Content

Games

Advanced

Brands

Industries

Rates

Creator requests

Request a creator

Authorizations

Headers

Body

Response