> ## 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.

# Fetch profile IDs by handle

> Fetch profile IDs for multiple platform handles in a single request.

This lightweight endpoint returns only the handle-to-ID mapping, not full profile data.
Use the returned IDs with other endpoints to fetch profile details, content, and analysis.

This endpoint costs a flat rate of 1 credit, regardless of how many handles are
requested (up to 100).




## OpenAPI

````yaml POST /platforms/{platform}/profiles/lookup
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, and TikTok.


    ## Authentication

    All requests require an API key in the `x-api-key` header.


    ## Rate Limiting

    The API uses a weight-based quota system:

    - Single item requests: 1 quota unit

    - Bulk requests: 1 quota unit per item (up to 100 items)

    - List requests: 1 quota unit per item returned (based on `limit`)

    - Advanced endpoint: 100 quota units per request


    Rate limit headers are included in all responses:

    - `X-RateLimit-{window}-limit`: Maximum requests allowed

    - `X-RateLimit-{window}-remaining`: Remaining requests

    - `X-RateLimit-{window}-reset`: ISO timestamp when limit resets


    ### Quota weights by endpoint:

    - Profile/Content endpoints: 1 quota unit per item

    - Analysis endpoint: 100 quota units per request

    - Email endpoint: 10 quota units per request

    - Socials endpoint: 10 quota units per request

    - Audience endpoint: 100 quota units per request


    ## 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
paths:
  /platforms/{platform}/profiles/lookup:
    post:
      tags:
        - Profiles
      summary: Fetch profile IDs by handle
      description: >
        Fetch profile IDs for multiple platform handles in a single request.


        This lightweight endpoint returns only the handle-to-ID mapping, not
        full profile data.

        Use the returned IDs with other endpoints to fetch profile details,
        content, and analysis.


        This endpoint costs a flat rate of 1 credit, regardless of how many
        handles are

        requested (up to 100).
      operationId: bulkLookupHandles
      parameters:
        - $ref: '#/components/parameters/Platform'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - handles
              properties:
                handles:
                  type: array
                  items:
                    type: string
                  minItems: 1
                  maxItems: 100
                  description: Array of platform handles to look up
                  example:
                    - streamer123
                    - '@gamer456'
                    - creator789
      responses:
        '200':
          description: Handle lookup results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandleLookupResponse'
              example:
                payload:
                  - handle: streamer123
                    id: '484563826'
                  - handle: gamer456
                    id: '775305965'
                meta:
                  missing_handles:
                    - creator789
                  received_at: '2025-01-27T12:00:00.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    Platform:
      name: platform
      in: path
      required: true
      description: Platform identifier
      schema:
        type: string
        enum:
          - twitch
          - youtube
          - instagram
          - tiktok
        example: twitch
  schemas:
    HandleLookupResponse:
      type: object
      properties:
        payload:
          type: array
          items:
            $ref: '#/components/schemas/HandleMapping'
        meta:
          allOf:
            - $ref: '#/components/schemas/Meta'
            - type: object
              properties:
                missing_handles:
                  type: array
                  items:
                    type: string
                  description: Handles that were not found
    HandleMapping:
      type: object
      properties:
        handle:
          type: string
          description: The platform handle/username
        id:
          type: string
          description: The platform-specific profile ID
    Meta:
      type: object
      properties:
        source:
          type: string
        received_at:
          type: string
          format: date-time
        request_id:
          type: string
          format: uuid
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: integer
            message:
              type: string
        meta:
          type: object
          properties:
            request_id:
              type: string
              format: uuid
  responses:
    BadRequest:
      description: Bad request - validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              status: 400
              message: Invalid platform or missing required parameter
            meta:
              request_id: 5e7c0137-1ed3-4b4b-8e5f-3d9cf00f7ac4
    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.

````