captapi-com Batch API

openapi: 3.2.0
info:
  title: Captapi Batch API
  version: 0.1.0
  summary: Structured public data from social platforms through one REST API.
  description: 'Captapi returns public data (profiles, posts, comments, transcripts, search, ads, commerce) from social platforms as JSON.


    Auth: send your key as `Authorization: Bearer capt_live_...` or `X-API-Key: capt_live_...`. Keys are created by a human at https://captapi.com/dashboard/api-keys.


    Billing: each operation states its cost in `x-credit-cost`. The `X-Captapi-Credits` response header shows what was charged. Failed requests (4xx/5xx) are not billed. `cache=true` serves from the 24h cache, free on a hit where `billedOnCacheHit` is false. Where the price depends on which path served the call, `x-credit-cost.note` gives the full rule and the range we have observed.


    Empty results: on many list and search endpoints a call that ran but found nothing is charged 0 credits (for example an ad-library or profile search with no matches). Where an empty result is still billed, the endpoint description says so; Google Maps business search, for instance, bills its one page because the lookup ran. The `X-Captapi-Credits` header always shows the actual charge.


    Errors: every non-2xx response uses the same envelope, `{ success: false, error: { code, message, retryable } }`. Retry only when `retryable` is true, honouring `Retry-After`.


    Timing: every response carries `Server-Timing: total;dur=`, the total time the request took. Deprecated: the `timings` object some endpoints still return in `data` will be removed from response bodies on 2026-12-17; use the header instead. It is not part of the response schemas below.


    Response schemas are inferred from real captured responses and list the fields seen there plus documented top-level fields. Fields can be null when a platform does not expose them.


    Endpoint list: https://captapi.com/llms-endpoints.txt · Guide for agents: https://captapi.com/llms.txt · MCP: https://captapi.com/mcp.json'
  contact:
    name: Captapi support
    email: support@captapi.com
    url: https://captapi.com
  termsOfService: https://captapi.com/legal/terms
  license:
    name: Captapi Terms of Service
    url: https://captapi.com/legal/terms
servers:
- url: https://api.captapi.com
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Batch
  description: Run several endpoint calls in one request.
paths:
  /v1/batch:
    post:
      operationId: run_batch
      tags:
      - Batch
      summary: Run up to 20 endpoint calls in one request
      description: 'Runs up to 20 Captapi GET calls in one request, 10 at a time, through the same auth, credit, cache and rate-limit pipeline as direct calls. Each item is billed exactly like the direct call and failed items are not billed. Results keep input order; each one carries the item''s HTTP status and its full response body. A failed item''s body uses the standard error envelope {success: false, error: {code, message, retryable}}, including BATCH_ITEM_TIMEOUT and BATCH_ITEM_FAILED when the item could not finish. An unknown path fails the whole batch with 400 before anything runs.'
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      x-credit-cost:
        label: Sum of the items; each is billed like a direct call
      x-one-liner: Runs up to 20 Captapi GET calls in one request, 10 at a time, through the same auth, credit, cache and rate-limit pipeline as direct calls.
      responses:
        '200':
          description: Success.
          headers:
            X-Captapi-Credits:
              $ref: '#/components/headers/Credits'
            X-Captapi-Cache:
              $ref: '#/components/headers/Cache'
            X-Captapi-Request-Id:
              $ref: '#/components/headers/RequestId'
            Server-Timing:
              $ref: '#/components/headers/ServerTiming'
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - data
                properties:
                  success:
                    const: true
                  data:
                    type: object
                    properties:
                      total:
                        type: integer
                      succeeded:
                        type: integer
                      failed:
                        type: integer
                      results:
                        type: array
                        items:
                          type: object
                          properties:
                            path:
                              type: string
                            params:
                              type: object
                              properties:
                                url:
                                  type: string
                            status:
                              type: integer
                            body:
                              type: object
                              properties:
                                success:
                                  type: boolean
                                data:
                                  type: object
                                  properties:
                                    platform:
                                      type: string
                                    username:
                                      type: string
                                error:
                                  type: object
                                  properties:
                                    code:
                                      type: string
                                    message:
                                      type: string
                                    retryable:
                                      type: boolean
              example:
                success: true
                data:
                  total: 2
                  succeeded: 1
                  failed: 1
                  results:
                  - path: /v1/twitter/profile
                    params:
                      url: https://x.com/NASA
                    status: 200
                    body:
                      success: true
                      data:
                        platform: twitter
                        username: NASA
                  - path: /v1/tiktok/video-details
                    params:
                      url: https://www.youtube.com/watch?v=dQw4w9WgXcQ
                    status: 400
                    body:
                      success: false
                      error:
                        code: WRONG_RESOURCE_TYPE
                        message: Expected a TikTok URL, but received a YouTube URL.
                        retryable: false
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '404':
          $ref: '#/components/responses/Error404'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
            example:
              requests:
              - path: /v1/youtube/video-details
                params:
                  url: https://www.youtube.com/watch?v=iG9CE55wbtY
              - path: /v1/reddit/subreddit-posts
                params:
                  url: https://www.reddit.com/r/programming/
                  limit: 5
        required: true
components:
  schemas:
    BatchRequest:
      properties:
        requests:
          items:
            $ref: '#/components/schemas/BatchItem'
          type: array
          maxItems: 20
          minItems: 1
          title: Requests
      type: object
      required:
      - requests
      title: BatchRequest
    Error:
      type: object
      required:
      - success
      - error
      properties:
        success:
          const: false
        error:
          type: object
          required:
          - code
          - message
          - retryable
          properties:
            code:
              type: string
              description: Machine-readable error code, e.g. WRONG_RESOURCE_TYPE, NOT_FOUND, insufficient_credits, rate_limit_exceeded. Compare case-sensitively; both upper and lower case codes exist.
            message:
              type: string
              description: Human-readable explanation.
            retryable:
              type: boolean
              description: true when the same request may succeed later (429, most 5xx). Do not retry when false.
            suggestedEndpoint:
              type:
              - string
              - 'null'
              description: On platform mismatch, the endpoint that matches the URL you sent.
          additionalProperties: true
    BatchItem:
      properties:
        path:
          type: string
          title: Path
          description: Captapi GET path, e.g. /v1/youtube/video-details
        params:
          additionalProperties: true
          type: object
          title: Params
      type: object
      required:
      - path
      title: BatchItem
  responses:
    Error429:
      description: Rate limit reached. Wait for Retry-After seconds. Not billed.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: rate_limit_exceeded
              message: rate limit exceeded
              retryable: true
              plan: starter
              limit_per_minute: 120
    Error422:
      description: A required parameter is missing or has the wrong type. Not billed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: VALIDATION_ERROR
              message: Request validation failed. Fix the listed fields and retry.
              retryable: false
              issues:
              - type: missing
                loc:
                - query
                - url
                msg: Field required
                input: null
    Error404:
      description: The resource does not exist or is not public. Not billed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: NOT_FOUND
              message: Monitor not found
              retryable: false
    Error401:
      description: Missing, invalid or revoked API key. Not billed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: UNAUTHORIZED
              message: Invalid or revoked API key
              retryable: false
    Error400:
      description: 'Bad request: wrong platform URL, unknown endpoint, or an invalid parameter value. Not billed.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: WRONG_RESOURCE_TYPE
              message: Expected a TikTok URL, but received a YouTube URL. Use the YouTube endpoint for that URL, or pass a TikTok URL like https://www.tiktok.com/@user/video/1234567890.
              retryable: false
              suggestedEndpoint: /v1/youtube/video-details
  headers:
    ServerTiming:
      description: 'Total time the request took, in milliseconds: `total;dur=<ms>`. No per-step breakdown.'
      schema:
        type: string
      example: total;dur=4387
    Cache:
      description: 1 when the response was served from the 24h cache, 0 otherwise.
      schema:
        type: string
        enum:
        - '0'
        - '1'
    RequestId:
      description: Request id. Include it when contacting support.
      schema:
        type: string
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    Credits:
      description: Credits charged for this request. 0 on a free cache hit or a failed request.
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key: `Authorization: Bearer capt_live_...`. Create one at https://captapi.com/dashboard/api-keys.'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Alternative to the bearer header: `X-API-Key: capt_live_...`.'
externalDocs:
  description: Docs
  url: https://captapi.com/docs