> ## Documentation Index > Fetch the complete documentation index at: https://docs.streamforge.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml POST /creator-requests openapi: 3.0.3 info: title: Streamforge External API description: > Public-facing API for accessing normalized creator, content, and analysis data across Twitch, YouTube, Instagram, TikTok, and X (Twitter). ## Authentication All requests require an API key in the `x-api-key` header. ## Credits The API prices calls in credits. Each call costs its endpoint's tier once, whatever the number of IDs it names or results it returns. A bulk call for 25 profiles costs the same as a call for one. The `X-Credits-limit`, `X-Credits-used` and `X-Credits-request-cost` response headers are in credits, so a call that costs 0.01 credit shows `X-Credits-request-cost: 0.01`. - Standard, 0.01 credit per call: creator profiles, posts and videos, games, creator and brand search, rate estimates - Advanced, 0.1 credit per call: creator email, cross-platform social linking, brand profiles, industry data, rate benchmarks - Premium, 1 credit per call: AI-enriched creator data, audience demographics, creator requests ### Credits by endpoint: - Profile, profile list, bulk profiles, handle lookup and creator search: 0.01 credit - Content, content lists and bulk content: 0.01 credit - Game, game content, bulk games and game search: 0.01 credit - Brand search and brand list: 0.01 credit - Rate dimensions and rate estimate: 0.01 credit - Email and socials endpoints: 0.1 credit - Brand profile endpoint: 0.1 credit - Industry list and industry ranking: 0.1 credit - Rate benchmarks: 0.1 credit - Analysis and audience endpoints: 1 credit - Creator request: 1 credit per accepted request, once, returned if it ends `not_found` or `failed`; reading a request costs nothing Brand, industry, rate and creator request endpoints are available with a Streamforge API key only. ## Items per call A call names or returns at most 25 items. Bulk calls take at most 25 IDs in `profile_ids`, `content_ids`, `game_ids` or `handles`; more returns a `400` validation error. A list page returns at most 25 items; a larger `limit` is lowered to 25. ## Rate Limiting Rate limit headers are included in all responses. Every call counts as one request, whatever it costs in credits: - `X-RateLimit-{window}-limit`: Maximum requests allowed - `X-RateLimit-{window}-remaining`: Remaining requests - `X-RateLimit-{window}-reset`: UNIX timestamp (seconds) when the limit resets ## Base URL Production: `https://external-api.streamforge.com` version: 1.0.0 contact: name: Streamforge Support email: support@streamforge.com servers: - url: https://external-api.streamforge.com description: Production - url: http://localhost:3000 description: Local development (from .env) variables: base_url: default: http://localhost:3000 security: - ApiKeyAuth: [] tags: - name: Health description: Health check endpoint - name: Profiles description: Creator profile endpoints - name: Content description: Content (streams/videos) endpoints - name: Games description: Game metadata endpoints - name: Advanced description: Advanced insights and analysis - name: Brands description: Brand sponsorship activity from Streamforge Market Intelligence - name: Industries description: >- Industry sponsorship totals and brand rankings from Streamforge Market Intelligence - name: Rates description: Sponsorship rate ranges from Streamforge's published rate snapshot - name: Creator requests description: Ask Streamforge to prepare a creator, then check back for the result paths: /creator-requests: post: tags: - Creator requests summary: Request a creator description: > 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. operationId: createCreatorRequest parameters: - $ref: '#/components/parameters/CreatorRequestEndUser' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatorRequestInput' examples: handle: summary: Platform and handle value: platform: youtube handle: '@examplecreator' profile_id: summary: Platform and profile ID, profile only value: platform: twitch profile_id: '484563826' audience: false url: summary: Profile URL value: url: https://www.youtube.com/@examplecreator responses: '200': description: >- The request has finished. `payload.status` is `ready`, `partial`, `not_found` or `failed` content: application/json: schema: $ref: '#/components/schemas/CreatorRequestResponse' example: 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 '202': description: >- The request was accepted and is in progress. `payload.status` is `pending` or `processing` headers: Retry-After: schema: type: integer description: Seconds to wait before reading the request Location: schema: type: string description: Where to read the request (`payload.status_url`) content: application/json: schema: $ref: '#/components/schemas/CreatorRequestResponse' example: 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 '400': description: > The body is not one of the accepted shapes (`Validation failed`), or it names something that is not a creator: `unsupported_profile_url`, `platform_mismatch` (the URL belongs to another platform than `platform`), `invalid_handle` or `invalid_profile_id`. For API keys with a per-end-user allowance, also `end_user_required` and `end_user_invalid`. content: application/json: schema: $ref: '#/components/schemas/CreatorRequestError' example: 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 '401': $ref: '#/components/responses/Unauthorized' '403': description: > Invalid or revoked API key; not enough credits left for the request (`Credits exceeded`); or the request came through RapidAPI (`direct_key_only`) content: application/json: schema: $ref: '#/components/schemas/CreatorRequestError' example: error: message: Credits exceeded status: 403 code: credits_exceeded meta: request_id: 5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4 '429': description: > Rate limit exceeded. For API keys with a per-end-user allowance, also `end_user_daily_limit`, `end_user_active_request` (with the request in progress in `meta.active_request`) and `preview_daily_limit`; these carry `meta.end_user_limit`. headers: Retry-After: schema: type: integer description: Seconds until retry is safe content: application/json: schema: $ref: '#/components/schemas/CreatorRequestError' example: error: message: Rate limit exceeded status: 429 meta: request_id: 5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4 '503': description: > The creator cannot be prepared right now, and nothing was charged. `preparation_unavailable`: try again shortly. `preparation_budget_exhausted`: the daily capacity for preparing new creators is used up; try again after the daily reset. `creator_requests_unavailable`, `creator_request_conflict` and `preview_limits_unavailable`: try again shortly. headers: Retry-After: schema: type: integer description: Seconds until retry is safe content: application/json: schema: $ref: '#/components/schemas/CreatorRequestError' example: 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 components: parameters: CreatorRequestEndUser: name: x-streamforge-end-user in: header required: false description: > 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. schema: type: string pattern: ^[A-Za-z0-9_-]{8,128}$ example: 8f2c1d7ab0e94c53 schemas: CreatorRequestInput: type: object description: > 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. properties: platform: type: string enum: - twitch - youtube - instagram - tiktok - twitter handle: type: string description: >- The creator's handle on the platform. Case does not matter and a leading `@` is ignored example: examplecreator profile_id: type: string description: >- Platform-specific creator ID. For YouTube, a channel ID (`UC` followed by 22 characters) example: '484563826' url: type: string description: > 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: type: boolean default: true description: Whether to produce the audience analysis as well as the profile CreatorRequestResponse: type: object properties: payload: $ref: '#/components/schemas/CreatorRequest' meta: type: object properties: received_at: type: string format: date-time credits_charged: type: number description: > Credits the request has cost in total: 1 once accepted, 0 if it was returned because the request ended `not_found` or `failed` example: 1 end_user_limit: $ref: '#/components/schemas/CreatorRequestEndUserLimit' CreatorRequestError: type: object properties: error: type: object properties: status: type: integer message: type: string code: type: string description: A machine-readable reason, on the errors that have one meta: type: object properties: request_id: type: string format: uuid end_user_limit: $ref: '#/components/schemas/CreatorRequestEndUserLimit' active_request: type: object description: >- With `end_user_active_request`, the request that is still in progress properties: request_id: type: string status_url: type: string CreatorRequest: type: object properties: request_id: type: string description: >- Identifies the request. Use it with `GET /creator-requests/{request_id}` example: cr_3f9a1c2b4d5e6f708192a3b4c5d6e7f8 status: type: string enum: - pending - processing - ready - partial - not_found - failed description: > `pending` and `processing`: in progress. `ready`: everything asked for is in `result`. `partial`: the profile is in `result`, the audience analysis is not. `not_found`: no such creator on the platform. `failed`: the request could not be completed stage: type: string enum: - queued - resolving_profile - fetching_profile - analyzing_audience - done description: What is being worked on, for display progress: type: integer minimum: 0 maximum: 100 description: >- A rough indication of progress, for display. It is 100 only once the request has finished message: type: string description: A short description of the current state, for display platform: type: string enum: - twitch - youtube - instagram - tiktok - twitter handle: type: string nullable: true description: >- The creator's handle, lowercase and without `@`, when the request named one or it is known profile_id: type: string nullable: true description: > The creator's platform-specific ID once it is known. Use it with the profile, content and analysis endpoints parts: type: object properties: profile: type: string enum: - pending - ready - not_found audience: type: string enum: - pending - ready - insufficient_data - unsupported - failed - unavailable - not_requested description: > `insufficient_data`: there is not enough public audience data for this creator. `unsupported`: an audience analysis is not available for this creator on this platform. `failed`: the analysis could not be completed. `unavailable`: no analysis was produced, because the daily capacity for new analyses is used up (`audience_reason` says so) or because the creator was not found. `not_requested`: the request was made with `audience: false` audience_reason: type: string nullable: true description: > Why the audience analysis is not available, as a sentence, when there is a reason to give. `null` otherwise, including while it is pending, when it is ready and when it was not requested poll_after_seconds: type: integer nullable: true description: >- Seconds to wait before reading the request again. `null` once the request has finished status_url: type: string description: The path of `GET /creator-requests/{request_id}` for this request example: /creator-requests/cr_3f9a1c2b4d5e6f708192a3b4c5d6e7f8 result: type: object nullable: true description: > The data, from the moment the profile can be served (`parts.profile` is `ready`); `null` before that and for a request that ended `not_found` properties: profile: $ref: '#/components/schemas/Profile' audience: type: object nullable: true description: > The audience analysis: the same object `GET /platforms/{platform}/profiles/{profile_id}/audience` returns as its `payload` (see that endpoint for the fields). `null` unless `parts.audience` is `ready` audience_updated_at: type: string format: date-time nullable: true description: >- When the audience analysis was generated (`meta.last_updated_at` of the audience endpoint) CreatorRequestEndUserLimit: type: object description: > The allowance of the end user named in `x-streamforge-end-user`. Only for API keys that carry a per-end-user allowance properties: cap: type: integer description: Different creators the end user can request per day remaining: type: integer description: How many of those are left today resets_at: type: string format: date-time description: When the allowance resets (midnight UTC) Error: type: object properties: error: type: object properties: status: type: integer message: type: string meta: type: object properties: request_id: type: string format: uuid Profile: type: object properties: platform_id: type: string enum: - twitch - youtube - instagram - tiktok - twitter id: type: string name: type: string display_name: type: string url: type: string format: uri description: type: string nullable: true profile_image: type: string format: uri nullable: true banner_image: type: string format: uri nullable: true language: type: string nullable: true statistics: type: object properties: followers: type: integer nullable: true views: type: integer nullable: true description: Total view count. Only available for YouTube profiles. views_estimated: type: integer nullable: true description: >- Estimated total view count calculated using our algorithms. Only available for Twitch profiles. following: type: integer nullable: true description: >- Number of accounts the creator follows. Only available for X (Twitter) profiles. posts: type: integer nullable: true description: Total post count. Only available for X (Twitter) profiles. is_verified: type: boolean description: Whether the account carries a verification badge (X only) is_protected: type: boolean description: Whether the account's posts are protected (X only) account_type: type: string description: >- Partner for partnered accounts, affiliate for affiliate accounts (Twitch only) nullable: true is_mature: type: boolean description: Whether the creator's content is marked as mature (Twitch only) nullable: true updated_at: type: string format: date-time last_active_at: type: string format: date-time nullable: true responses: Unauthorized: description: Missing API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: status: 401 message: API key is required meta: request_id: 5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4 securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: | Your API key. Include it in the `x-api-key` header for all requests. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.