SocialCrawl AI Search API

openapi: 3.2.0
info:
  title: SocialCrawl AI Search 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: ai-search
  description: Ai-search endpoints
paths:
  /prism/ai-visibility:
    get:
      summary: 'AI Share-of-Voice / GEO monitoring: prompt set x reruns to per-brand appearance-% per AI engine plus a cited-domain ranking.'
      description: Probes your brand (and competitors) across grounded-answer AI engines (Perplexity Sonar + Grok) over a prompt set with N reruns, then reports the share of runs your brand appeared in per engine (appearance-%, never volatile rank) plus a ranking of the domains those engines cite. Add include=web_baseline to see which AI-cited domains you do not yet rank on. Metered 2 credits per probe (one prompt x run x engine); use preset=quick|standard|deep for a flat budget. v1 detects mentions deterministically via recognition tokens. Supply brand plus prompts (or a topic). The self-serve entry tier of Profound/Otterly/Peec.
      tags:
      - ai-search
      operationId: get_prism_ai_visibility
      security:
      - ApiKeyAuth: []
      x-credit-tier: advanced
      x-credit-cost: 2
      x-socialcrawl-oneOf:
      - - topic
        - prompts
      parameters:
      - name: brand
        in: query
        required: true
        description: The brand whose appearance-% is measured (required). Matched against each answer plus its aliases.
        schema:
          type: string
      - name: prompts
        in: query
        required: false
        description: 'The category prompts to probe, as a JSON array or a pipe-delimited list (1-20). One of prompts or topic is required. (one of: topic, prompts; at least one required)'
        schema:
          type: string
      - name: topic
        in: query
        required: false
        description: 'A topic probed as a single prompt in v1 (one of prompts or topic is required). (one of: topic, prompts; at least one required)'
        schema:
          type: string
      - name: competitors
        in: query
        required: false
        description: CSV of up to 5 competitors also measured for appearance-% from the same answers.
        schema:
          type: string
      - name: engines
        in: query
        required: false
        description: 'CSV subset of perplexity,grok (default both): the grounded-answer engines probed.'
        schema:
          type: string
      - name: runs
        in: query
        required: false
        description: Reruns per (prompt, engine) to measure variance (1-20, default 8).
        schema:
          type: integer
      - name: preset
        in: query
        required: false
        description: 'quick|standard|deep: sets runs and caps prompts for a flat probe budget.'
        schema:
          type: string
          enum:
          - quick
          - standard
          - deep
      - name: include
        in: query
        required: false
        description: Set web_baseline to cross-join AI-cited domains against your web top domains.
        schema:
          type: string
      - name: brand_domains
        in: query
        required: false
        description: CSV of your own domains so the citation ranking can flag the ones you already rank on.
        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'
components:
  responses:
    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'
    Error401:
      description: Unauthorized - missing or invalid API key
      x-error-codes:
      - MISSING_API_KEY
      - INVALID_API_KEY
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Error402:
      description: Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit
      x-error-codes:
      - INSUFFICIENT_CREDITS
      - KEY_BUDGET_EXCEEDED
      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'
    Error502:
      description: Upstream error - the platform returned an error, credits refunded
      x-error-codes:
      - UPSTREAM_ERROR
      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'
    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'
    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:
          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'
  schemas:
    ErrorEnvelope:
      type: object
      description: Unified error response envelope. Every 4xx/5xx response returns this shape; `error.type` is a machine-readable code from the API's error catalog.
      properties:
        success:
          type: boolean
          enum:
          - false
          description: Always false on an error response.
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - MISSING_API_KEY
              - INVALID_API_KEY
              - INSUFFICIENT_CREDITS
              - INVALID_REQUEST
              - ENDPOINT_NOT_FOUND
              - RESOURCE_NOT_FOUND
              - CONCURRENCY_LIMIT
              - UPSTREAM_ERROR
              - SERVICE_UNAVAILABLE
              - INTERNAL_ERROR
              - METHOD_NOT_ALLOWED
              - IDEMPOTENCY_KEY_CONFLICT
              - IDEMPOTENCY_KEY_PAYLOAD_MISMATCH
              - COHORT_MEMBER_LIMIT_EXCEEDED
              - COHORT_LIMIT_EXCEEDED
              - COHORT_IDENTITY_PLATFORM_UNSUPPORTED
              - COHORT_IDENTITY_CONFLICT
              - COHORT_QUERY_NOT_CANCELLABLE
              - COHORT_QUERY_NOT_READY
              - COHORT_RESULT_TOO_LARGE
              - PAYLOAD_TOO_LARGE
              - RATE_LIMITED
              - KEY_BUDGET_EXCEEDED
              description: Machine-readable error code. The per-status `x-error-codes` list on each response narrows which codes that status can carry.
            message:
              type: string
              description: Human-readable explanation of the error.
            status:
              type: integer
              description: HTTP status code, echoed in the body.
            doc_url:
              type: string
              description: Link to the docs page for this error code.
            details:
              type:
              - object
              - 'null'
              additionalProperties: true
              description: Optional structured context (e.g. the comment-lookup not-found taxonomy). Omitted on ordinary errors.
          required:
          - type
          - message
          - status
          - doc_url
        credits_used:
          type: integer
          description: Net credits charged for this request. Error paths deduct-then-refund, so this is 0 in almost every case; a partial-coverage composite may keep the succeeded-leg cost.
        credits_remaining:
          type:
          - integer
          - 'null'
          description: Credits left after this request, or null when the balance could not be read (e.g. auth failed before lookup).
        request_id:
          type: string
          description: Unique request identifier - matches the X-Request-Id header. Quote it in support requests.
      required:
      - success
      - error
      - credits_used
      - credits_remaining
      - request_id
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key authentication. Send your key in the `x-api-key` request header on every call. Create and manage keys in the dashboard.
x-tagGroups:
- name: Account
  tags:
  - meta
- name: Cohorts - Audience Panels
  tags:
  - cohorts
- name: Universal Search
  tags:
  - search
  - ai-search
  - geo
- name: Prism - Composite Intelligence
  tags:
  - prism
- name: Social Platforms
  tags:
  - tiktok
  - instagram
  - youtube
  - facebook
  - facebook-ads
  - twitter
  - linkedin
  - linkedin-ads
  - reddit
  - threads
  - pinterest
  - twitch
  - truthsocial
  - snapchat
  - kick
  - bluesky
  - rumble
  - kwai
- name: Commerce & Reviews
  tags:
  - amazon
  - tiktokshop
  - app_store
  - google_play
  - google_shopping
  - trustpilot
  - tripadvisor
- name: Search, News & Web
  tags:
  - google
  - google-ads
  - google_news
  - google_finance
  - naver
  - perplexity
  - tavily
  - hackernews
  - github
  - content_analysis
  - polymarket
  - spotify
- name: Link in Bio
  tags:
  - linktree
  - komi
  - pillar
  - linkbio
  - linkme
- name: More Platforms
  tags:
  - apple_music
  - ebay
  - google_trends
  - home_depot
  - target
  - tiktok-ads
  - walmart
  - wayfair
  - web
- name: Utility
  tags:
  - utility
x-full-spec: https://www.socialcrawl.dev/openapi.json