SocialCrawl Tavily API

openapi: 3.2.0
info:
  title: SocialCrawl Tavily 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: tavily
  description: Tavily endpoints
paths:
  /tavily/search:
    get:
      summary: Tavily web search with optional LLM-generated answer
      description: Runs a web search via Tavily and returns ranked results plus an optional LLM-generated `answer` synthesised from the top sources. Set `include_answer=true` to enable answer synthesis. Use `search_depth=advanced` for higher-relevance results (also unlocks `chunks_per_source`). Filter results to specific domains via `include_domains` (comma-separated), or exclude via `exclude_domains`. Time-bounded queries via `time_range` (`d` / `w` / `m` / `y`) or explicit `start_date` / `end_date` (YYYY-MM-DD).
      tags:
      - tavily
      operationId: get_tavily_search
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 1
      parameters:
      - name: query
        in: query
        required: true
        description: 'The search query: natural-language free text.'
        schema:
          type: string
      - name: search_depth
        in: query
        required: false
        description: Latency-vs-relevance tradeoff. `basic` is the default; `advanced` unlocks `chunks_per_source` and higher-relevance ranking.
        schema:
          type: string
          enum:
          - basic
          - advanced
          - fast
          - ultra-fast
      - name: topic
        in: query
        required: false
        description: Search category. Defaults to `general`. Use `news` for time-sensitive queries and `finance` for market data.
        schema:
          type: string
          enum:
          - general
          - news
          - finance
      - name: time_range
        in: query
        required: false
        description: Time window relative to now. Accepts `day` / `week` / `month` / `year` (or shorthand `d` / `w` / `m` / `y`).
        schema:
          type: string
          enum:
          - day
          - week
          - month
          - year
          - d
          - w
          - m
          - y
      - name: max_results
        in: query
        required: false
        description: Number of results to return (1-20). Defaults to 5.
        schema:
          type: integer
      - name: chunks_per_source
        in: query
        required: false
        description: Max relevant chunks returned per source (1-5). Only honoured when `search_depth=advanced`. Defaults to 3.
        schema:
          type: integer
      - name: include_images
        in: query
        required: false
        description: Include images alongside the result content.
        schema:
          type: boolean
      - name: include_image_descriptions
        in: query
        required: false
        description: Include AI-generated descriptions for the returned images.
        schema:
          type: boolean
      - name: include_answer
        in: query
        required: false
        description: Include an LLM-generated answer string synthesised from the top sources.
        schema:
          type: boolean
      - name: include_raw_content
        in: query
        required: false
        description: Include the raw HTML/text alongside the cleaned content.
        schema:
          type: boolean
      - name: include_domains
        in: query
        required: false
        description: Comma-separated list of domains to restrict results to (e.g. `nytimes.com,reuters.com`).
        schema:
          type: string
      - name: exclude_domains
        in: query
        required: false
        description: Comma-separated list of domains to exclude from results.
        schema:
          type: string
      - name: country
        in: query
        required: false
        description: ISO 3166-1 alpha-2 country code to bias results toward.
        schema:
          type: string
      - name: start_date
        in: query
        required: false
        description: Inclusive lower bound on result publish date (YYYY-MM-DD).
        schema:
          type: string
      - name: end_date
        in: query
        required: false
        description: Inclusive upper bound on result publish date (YYYY-MM-DD).
        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'
  /tavily/extract:
    get:
      summary: Extract clean content from one or more URLs
      description: Pulls clean, AI-ready text out of one or more URLs via Tavily's extractor. Pass a single URL or a comma-separated list (max 20). Returns extracted content per URL alongside any URLs that failed extraction. Use `extract_depth=advanced` for harder pages (paywalls, JS-heavy SPAs).
      tags:
      - tavily
      operationId: get_tavily_extract
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 1
      parameters:
      - name: urls
        in: query
        required: true
        description: Comma-separated list of URLs to extract (max 20).
        schema:
          type: string
      - name: extract_depth
        in: query
        required: false
        description: Extraction strategy. `basic` is the default and faster; `advanced` handles harder pages but takes longer.
        schema:
          type: string
          enum:
          - basic
          - advanced
      - name: format
        in: query
        required: false
        description: Output format for the extracted content. `markdown` (default) preserves structure; `text` is plain.
        schema:
          type: string
          enum:
          - markdown
          - text
      - name: include_images
        in: query
        required: false
        description: Include images extracted from each URL.
        schema:
          type: boolean
      - name: include_favicon
        in: query
        required: false
        description: Include the favicon URL for each page.
        schema:
          type: boolean
      - name: timeout
        in: query
        required: false
        description: Per-URL timeout in seconds (1-60).
        schema:
          type: integer
      - 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'
  /tavily/map:
    get:
      summary: Map a website's sitegraph
      description: 'Returns the sitegraph of a website starting from a root URL: a list of discovered URLs without their full content. Cheaper and faster than crawl when you only need to enumerate pages (e.g. for sitemap discovery or coverage analysis). Use `instructions` to guide the mapper in natural language and the `select_*` / `exclude_*` filters (regex patterns, comma-separated) to narrow scope.'
      tags:
      - tavily
      operationId: get_tavily_map
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 1
      parameters:
      - name: url
        in: query
        required: true
        description: Root URL to begin mapping.
        schema:
          type: string
      - name: max_depth
        in: query
        required: false
        description: Maximum link depth from the root URL. Defaults to 1.
        schema:
          type: integer
      - name: max_breadth
        in: query
        required: false
        description: Maximum number of links followed per level (per page). Defaults to 20.
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Total number of links the mapper will process before stopping. Defaults to 50.
        schema:
          type: integer
      - name: instructions
        in: query
        required: false
        description: Natural-language instructions for the mapper (e.g. 'Find all pages related to API documentation').
        schema:
          type: string
      - name: select_paths
        in: query
        required: false
        description: 'Comma-separated regex patterns: only include URLs whose path matches.'
        schema:
          type: string
      - name: select_domains
        in: query
        required: false
        description: 'Comma-separated regex patterns: only include URLs whose domain matches.'
        schema:
          type: string
      - name: exclude_paths
        in: query
        required: false
        description: 'Comma-separated regex patterns: exclude URLs whose path matches.'
        schema:
          type: string
      - name: exclude_domains
        in: query
        required: false
        description: 'Comma-separated regex patterns: exclude URLs whose domain matches.'
        schema:
          type: string
      - name: allow_external
        in: query
        required: false
        description: Whether to follow / return links to external domains. Defaults to true.
        schema:
          type: boolean
      - name: timeout
        in: query
        required: false
        description: Maximum time in seconds (10-150).
        schema:
          type: integer
      - name: categories
        in: query
        required: false
        description: Comma-separated list of category hints to bias mapping toward.
        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'
  /tavily/crawl:
    get:
      summary: Crawl a website with LLM-driven path selection
      description: Multi-page crawl starting from a root URL. Returns each crawled page with its extracted content (unlike map, which returns only URLs). Use `instructions` to guide the crawler in natural language. Tavily uses an LLM to follow only the paths matching your intent. Use `select_*` / `exclude_*` filters (comma-separated regex patterns) to constrain scope.
      tags:
      - tavily
      operationId: get_tavily_crawl
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 1
      parameters:
      - name: url
        in: query
        required: true
        description: Root URL to begin crawling.
        schema:
          type: string
      - name: max_depth
        in: query
        required: false
        description: Maximum link depth from the root URL. Defaults to 1.
        schema:
          type: integer
      - name: max_breadth
        in: query
        required: false
        description: Maximum number of links followed per level (per page). Defaults to 20.
        schema:
          type: integer
      - name: limit
        in: query
        required: false
        description: Total number of pages the crawler will process before stopping. Defaults to 50.
        schema:
          type: integer
      - name: instructions
        in: query
        required: false
        description: Natural-language instructions for the crawler (e.g. 'Find all product pages with pricing').
        schema:
          type: string
      - name: select_paths
        in: query
        required: false
        description: 'Comma-separated regex patterns: only crawl URLs whose path matches.'
        schema:
          type: string
      - name: select_domains
        in: query
        required: false
        description: 'Comma-separated regex patterns: only crawl URLs whose domain matches.'
        schema:
          type: string
      - name: exclude_paths
        in: query
        required: false
        description: 'Comma-separated regex patterns: skip URLs whose path matches.'
        schema:
          type: string
      - name: exclude_domains
        in: query
        required: false
        description: 'Comma-separated regex patterns: skip URLs whose domain matches.'
        schema:
          type: string
      - name: allow_external
        in: query
        required: false
        description: Whether to follow links to external domains. Defaults to true.
        schema:
          type: boolean
      - name: extract_depth
        in: query
        required: false
        description: Per-page extraction strategy. `basic` is faster; `advanced` handles harder pages.
        schema:
          type: string
          enum:
          - basic
          - advanced
      - name: format
        in: query
        required: false
        description: Output format for extracted content. `markdown` (default) or `text`.
        schema:
          type: string
          enum:
          - markdown
          - text
      - name: categories
        in: query
        required: false
        description: Comma-separated list of category hints to bias the crawl toward.
        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 repla

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