> ## 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. # Get a creator request > Read a request made with `POST /creator-requests`. The body is the same as that endpoint's. While the request is in progress the answer is `202` with `Retry-After` and `Location`; wait, then read it again. Once the request has finished the answer is `200`, and later reads return the same outcome. See `POST /creator-requests` for what each status and each `parts.audience` value means. `result.profile` is filled in as soon as the profile can be served, which can be while the audience analysis is still in progress. Reading a request costs no credits. Each read does count towards your per-minute rate limit, so wait `poll_after_seconds` between reads. A request can be read only with the API key that created it; with any other key the answer is `404`. A request stays readable for 7 days. Available with a Streamforge API key only. ## OpenAPI ````yaml GET /creator-requests/{request_id} 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/{request_id}: get: tags: - Creator requests summary: Get a creator request description: > Read a request made with `POST /creator-requests`. The body is the same as that endpoint's. While the request is in progress the answer is `202` with `Retry-After` and `Location`; wait, then read it again. Once the request has finished the answer is `200`, and later reads return the same outcome. See `POST /creator-requests` for what each status and each `parts.audience` value means. `result.profile` is filled in as soon as the profile can be served, which can be while the audience analysis is still in progress. Reading a request costs no credits. Each read does count towards your per-minute rate limit, so wait `poll_after_seconds` between reads. A request can be read only with the API key that created it; with any other key the answer is `404`. A request stays readable for 7 days. Available with a Streamforge API key only. operationId: getCreatorRequest parameters: - $ref: '#/components/parameters/CreatorRequestId' - $ref: '#/components/parameters/CreatorRequestEndUser' 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: not_found stage: done progress: 100 message: Creator not found on this platform platform: youtube handle: examplecreator profile_id: null parts: profile: not_found audience: unavailable audience_reason: null poll_after_seconds: null status_url: /creator-requests/cr_3f9a1c2b4d5e6f708192a3b4c5d6e7f8 result: null meta: received_at: '2026-10-13T12:00:20.000Z' credits_charged: 0 '202': description: >- The request is still in progress. `payload.status` is `pending` or `processing` headers: Retry-After: schema: type: integer description: Seconds to wait before reading the request again 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: processing stage: analyzing_audience progress: 70 message: Analyzing the audience platform: twitch handle: streamer123 profile_id: '484563826' parts: profile: ready audience: pending audience_reason: null poll_after_seconds: 3 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:10.000Z' credits_charged: 1 '400': description: >- For API keys with a per-end-user allowance, `end_user_required` or `end_user_invalid` content: application/json: schema: $ref: '#/components/schemas/CreatorRequestError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: >- No such request, or it was created with another API key (`creator_request_not_found`) content: application/json: schema: $ref: '#/components/schemas/CreatorRequestError' example: error: message: Creator request not found status: 404 code: creator_request_not_found meta: request_id: 5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4 '429': $ref: '#/components/responses/TooManyRequests' '503': description: >- Requests cannot be read right now (`creator_requests_unavailable`, `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' components: parameters: CreatorRequestId: name: request_id in: path required: true description: The `request_id` returned by `POST /creator-requests` schema: type: string example: cr_3f9a1c2b4d5e6f708192a3b4c5d6e7f8 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: 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 Forbidden: description: Invalid or revoked API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: status: 403 message: Invalid API key meta: request_id: 5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4 TooManyRequests: description: Rate limit exceeded headers: Retry-After: schema: type: integer description: Seconds until retry is safe content: application/json: schema: $ref: '#/components/schemas/Error' example: error: status: 429 message: Rate limit exceeded 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.