SocialCrawl Utility API

openapi: 3.2.0
info:
  title: SocialCrawl Utility API
  version: 1.0.0
  description: 'Unified social media data API - one API key, one consistent response format, 50 platforms, 400 endpoints. Power AI agents with clean social data.


    Slim variant: inline examples removed and the shared error responses hoisted into components. The full annotated spec is at https://www.socialcrawl.dev/openapi.json.'
  contact:
    name: SocialCrawl
    url: https://www.socialcrawl.dev
    email: support@socialcrawl.dev
servers:
- url: https://www.socialcrawl.dev/v1
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Utility
  description: Utility endpoints
paths:
  /utility/endpoints:
    get:
      summary: List every available endpoint
      description: 'Machine-readable catalog of every active SocialCrawl endpoint: path, method, platform, credit cost, required and optional parameters, response archetype, and a link to the per-endpoint usage guide. Generated from the endpoint registry at request time, so it never drifts from what is callable. Free to call.'
      tags:
      - Utility
      operationId: get_utility_endpoints
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 0
      x-credit-cost-formula: Free (0 credits)
      parameters:
      - name: platform
        in: query
        required: false
        description: Filter the catalog to a single platform slug (e.g. tiktok)
        schema:
          type: string
      - name: search
        in: query
        required: false
        description: Case-insensitive substring filter over endpoint paths and summaries
        schema:
          type: string
      - name: method
        in: query
        required: false
        description: Filter by HTTP method (GET, POST, PATCH or DELETE)
        schema:
          type: string
          enum:
          - GET
          - POST
          - PATCH
          - DELETE
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      metrics:
                        type: object
                        description: Key performance metrics
                        properties:
                          total_views:
                            type: integer
                            description: Total view count
                          total_likes:
                            type: integer
                            description: Total like count
                          total_comments:
                            type: integer
                            description: Total comment count
                          engagement_rate:
                            type: number
                            description: Computed engagement rate (0-1)
                      period:
                        type:
                        - string
                        - 'null'
                        description: Time period for the analytics data
                      breakdown:
                        type:
                        - array
                        - 'null'
                        description: Per-item or per-period breakdown
                        items:
                          type: object
                          description: Breakdown entry
                      _warnings:
                        type: array
                        description: 'Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as ''no warnings''.'
                        items:
                          type: string
                          description: One advisory notice.
                  credits_used:
                    type: integer
                    description: Number of credits consumed
                  credits_remaining:
                    type:
                    - integer
                    - 'null'
                    description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
                  request_id:
                    type: string
                    description: Unique request identifier for support
                  cached:
                    type: boolean
                    description: Whether the response was served from cache
                  idempotent_replay:
                    type: boolean
                    description: True only when this response is an idempotency replay
                required:
                - success
                - platform
                - endpoint
                - data
                - credits_used
                - credits_remaining
                - request_id
                - cached
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '413':
          $ref: '#/components/responses/Error413'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
  /utility/endpoint:
    get:
      summary: How to use any endpoint
      description: 'Complete usage guide for a single endpoint: every parameter with type, description and example, the exact credit cost, cache behaviour, pagination recipe, a copy-paste example request, an example response, the response schema URL, and related endpoints. Identify the endpoint by id (tiktok/profile) or url (/v1/tiktok/profile). Free to call.'
      tags:
      - Utility
      operationId: get_utility_endpoint
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 0
      x-credit-cost-formula: Free (0 credits)
      x-socialcrawl-oneOf:
      - - id
        - url
      parameters:
      - name: id
        in: query
        required: false
        description: 'Endpoint id as platform/resource, e.g. tiktok/profile (one of: id, url; at least one required)'
        schema:
          type: string
      - name: url
        in: query
        required: false
        description: 'Endpoint path form, e.g. /v1/tiktok/profile (a full https URL also works) (one of: id, url; at least one required)'
        schema:
          type: string
      - name: method
        in: query
        required: false
        description: Disambiguates a resource registered under more than one HTTP method, e.g. /v1/web/monitors/{monitor_id} is GET, PATCH and DELETE. Omit it and the first registered method wins
        schema:
          type: string
          enum:
          - GET
          - POST
          - PATCH
          - DELETE
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      metrics:
                        type: object
                        description: Key performance metrics
                        properties:
                          total_views:
                            type: integer
                            description: Total view count
                          total_likes:
                            type: integer
                            description: Total like count
                          total_comments:
                            type: integer
                            description: Total comment count
                          engagement_rate:
                            type: number
                            description: Computed engagement rate (0-1)
                      period:
                        type:
                        - string
                        - 'null'
                        description: Time period for the analytics data
                      breakdown:
                        type:
                        - array
                        - 'null'
                        description: Per-item or per-period breakdown
                        items:
                          type: object
                          description: Breakdown entry
                      _warnings:
                        type: array
                        description: 'Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as ''no warnings''.'
                        items:
                          type: string
                          description: One advisory notice.
                  credits_used:
                    type: integer
                    description: Number of credits consumed
                  credits_remaining:
                    type:
                    - integer
                    - 'null'
                    description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
                  request_id:
                    type: string
                    description: Unique request identifier for support
                  cached:
                    type: boolean
                    description: Whether the response was served from cache
                  idempotent_replay:
                    type: boolean
                    description: True only when this response is an idempotency replay
                required:
                - success
                - platform
                - endpoint
                - data
                - credits_used
                - credits_remaining
                - request_id
                - cached
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '413':
          $ref: '#/components/responses/Error413'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
  /utility/quickstart:
    get:
      summary: Get started in one call
      description: 'Everything needed for a first successful API call in one response: authentication, base URL, the response envelope, the credit billing model, the error taxonomy, rate limits, pagination rules, and a copy-paste first request. Pass platform to tailor the first-call example. Free to call.'
      tags:
      - Utility
      operationId: get_utility_quickstart
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 0
      x-credit-cost-formula: Free (0 credits)
      parameters:
      - name: platform
        in: query
        required: false
        description: Tailor the first-call example and links to one platform slug
        schema:
          type: string
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      metrics:
                        type: object
                        description: Key performance metrics
                        properties:
                          total_views:
                            type: integer
                            description: Total view count
                          total_likes:
                            type: integer
                            description: Total like count
                          total_comments:
                            type: integer
                            description: Total comment count
                          engagement_rate:
                            type: number
                            description: Computed engagement rate (0-1)
                      period:
                        type:
                        - string
                        - 'null'
                        description: Time period for the analytics data
                      breakdown:
                        type:
                        - array
                        - 'null'
                        description: Per-item or per-period breakdown
                        items:
                          type: object
                          description: Breakdown entry
                      _warnings:
                        type: array
                        description: 'Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as ''no warnings''.'
                        items:
                          type: string
                          description: One advisory notice.
                  credits_used:
                    type: integer
                    description: Number of credits consumed
                  credits_remaining:
                    type:
                    - integer
                    - 'null'
                    description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
                  request_id:
                    type: string
                    description: Unique request identifier for support
                  cached:
                    type: boolean
                    description: Whether the response was served from cache
                  idempotent_replay:
                    type: boolean
                    description: True only when this response is an idempotency replay
                required:
                - success
                - platform
                - endpoint
                - data
                - credits_used
                - credits_remaining
                - request_id
                - cached
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '413':
          $ref: '#/components/responses/Error413'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
  /utility/llms:
    get:
      summary: AI-agent context payload
      description: 'The SocialCrawl context corpus for AI agents, served through the API: the same content as llms.txt for the whole API or a single platform, as markdown or structured JSON. An agent with an API key can bootstrap itself with one call instead of scraping documentation pages. Free to call.'
      tags:
      - Utility
      operationId: get_utility_llms
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 0
      x-credit-cost-formula: Free (0 credits)
      parameters:
      - name: platform
        in: query
        required: false
        description: Scope the context to one platform slug
        schema:
          type: string
      - name: format
        in: query
        required: false
        description: markdown (default) returns the llms corpus text; json returns a structured context object
        schema:
          type: string
          enum:
          - markdown
          - json
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      metrics:
                        type: object
                        description: Key performance metrics
                        properties:
                          total_views:
                            type: integer
                            description: Total view count
                          total_likes:
                            type: integer
                            description: Total like count
                          total_comments:
                            type: integer
                            description: Total comment count
                          engagement_rate:
                            type: number
                            description: Computed engagement rate (0-1)
                      period:
                        type:
                        - string
                        - 'null'
                        description: Time period for the analytics data
                      breakdown:
                        type:
                        - array
                        - 'null'
                        description: Per-item or per-period breakdown
                        items:
                          type: object
                          description: Breakdown entry
                      _warnings:
                        type: array
                        description: 'Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as ''no warnings''.'
                        items:
                          type: string
                          description: One advisory notice.
                  credits_used:
                    type: integer
                    description: Number of credits consumed
                  credits_remaining:
                    type:
                    - integer
                    - 'null'
                    description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
                  request_id:
                    type: string
                    description: Unique request identifier for support
                  cached:
                    type: boolean
                    description: Whether the response was served from cache
                  idempotent_replay:
                    type: boolean
                    description: True only when this response is an idempotency replay
                required:
                - success
                - platform
                - endpoint
                - data
                - credits_used
                - credits_remaining
                - request_id
                - cached
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '413':
          $ref: '#/components/responses/Error413'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
components:
  responses:
    Error413:
      description: 'Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling'
      x-error-codes:
      - PAYLOAD_TOO_LARGE
      - COHORT_RESULT_TOO_LARGE
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Error404:
      description: Not found - the endpoint does not exist, or the requested resource was not found upstream
      x-error-codes:
      - ENDPOINT_NOT_FOUND
      - RESOURCE_NOT_FOUND
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Error500:
      description: Internal server error - credits automatically refunded
      x-error-codes:
      - INTERNAL_ERROR
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Error503:
      description: Service unavailable - circuit breaker open for this platform, credits refunded
      x-error-codes:
      - SERVICE_UNAVAILABLE
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Error400:
      description: Invalid request - missing or malformed parameters
      x-error-codes:
      - INVALID_REQUEST
      - COHORT_MEMBER_LIMIT_EXCEEDED
      - COHORT_LIMIT_EXCEEDED
      - COHORT_IDENTITY_PLATFORM_UNSUPPORTED
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Error422:
      description: Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload
      x-error-codes:
      - IDEMPOTENCY_KEY_PAYLOAD_MISMATCH
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Error429:
      description: 'Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits.'
      x-error-codes:
      - RATE_LIMITED
      - CONCURRENCY_LIMIT
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Error409:
      description: Conflict - a request with this Idempotency-Key is still in flight, or the cohort resource is not in a state that allows this operation
      x-error-codes:
      - IDEMPOTENCY_KEY_CONFLICT
      - COHORT_IDENTITY_CONFLICT
      - COHORT_QUERY_NOT_CANCELLABLE
      - COHORT_QUERY_NOT_READY
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Error405:
      description: Method not allowed - wrong HTTP verb for this endpoint
      x-error-codes:
      - METHOD_NOT_ALLOWED
      content:
        application/json:
   

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socialcrawl/refs/heads/main/openapi/socialcrawl-utility-api-openapi.yml