Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: SocialCrawl Content Analysis 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: content_analysis
description: Content_analysis endpoints
paths:
/content_analysis/search:
get:
summary: Search web citations of a keyword with per-mention sentiment
description: 'Returns paginated web citations (news, blogs, ecommerce, message-boards, organization pages) that mention the keyword, each scored on a 6-axis emotional sentiment model (anger, happiness, love, sadness, share, fun) plus positive/negative/neutral connotation probabilities. This is web-wide brand listening over DataForSEO''s citation database: page-level mentions, not native platform posts. Cursor-paginated via `cursor`; `total` is the global match count, not the page size.'
tags:
- content_analysis
operationId: get_content_analysis_search
security:
- ApiKeyAuth: []
x-credit-tier: advanced
x-credit-cost: 20
parameters:
- name: keyword
in: query
required: true
description: Brand or term to find mentions of. Wrap in escaped double-quotes for an exact phrase (e.g. "logitech mouse").
schema:
type: string
- name: page_type
in: query
required: false
description: 'Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization. Translated to a page_types filter upstream.'
schema:
type: string
enum:
- ecommerce
- news
- blogs
- message-boards
- organization
- name: search_mode
in: query
required: false
description: as_is (default) returns every matching page; one_per_domain dedupes to the top page per domain.
schema:
type: string
enum:
- as_is
- one_per_domain
- name: limit
in: query
required: false
description: Number of citations to return per page (1-100, default 10). Paginate via `cursor` for more.
schema:
type: integer
- name: cursor
in: query
required: false
description: 'Opaque pagination cursor: pass the `next_cursor` from the previous response to fetch the next page.'
schema:
type: string
- name: order_by
in: query
required: false
description: Sort rules as "field,direction"; separate multiple rules with ";" (e.g. content_info.sentiment_connotations.anger,desc).
schema:
type: string
- name: filters
in: query
required: false
description: Advanced DataForSEO filter expression as a JSON array (≤8 conditions). Combined with page_type via AND when both are present.
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'
/content_analysis/summary:
get:
summary: Aggregate mention summary for a keyword
description: 'Returns a single roll-up over every web citation of the keyword: total mention count, top domains, sentiment-connotation totals, positive/negative/neutral splits, top text + page categories, and breakdowns by page type, country, and language. The fastest way to size and characterize a brand''s web-wide footprint in one call.'
tags:
- content_analysis
operationId: get_content_analysis_summary
security:
- ApiKeyAuth: []
x-credit-tier: advanced
x-credit-cost: 20
parameters:
- name: keyword
in: query
required: true
description: Brand or term to summarize.
schema:
type: string
- name: page_type
in: query
required: false
description: 'Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization.'
schema:
type: string
enum:
- ecommerce
- news
- blogs
- message-boards
- organization
- name: positive_connotation_threshold
in: query
required: false
description: Minimum positive-connotation probability (0-1, default 0.4) for a mention to count as positive.
schema:
type: string
- name: sentiments_connotation_threshold
in: query
required: false
description: Minimum sentiment-connotation probability (0-1, default 0.4) for the 6-axis emotion buckets.
schema:
type: string
- name: internal_list_limit
in: query
required: false
description: Cap on internal arrays such as top_domains / categories (1-20).
schema:
type: integer
- name: filters
in: query
required: false
description: Advanced DataForSEO filter expression as a JSON array (≤8 conditions).
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'
/content_analysis/sentiment:
get:
summary: Sentiment breakdown for a keyword
description: 'Returns two sentiment distributions for the keyword''s web mentions: a positive/negative/neutral split (each a full summary sub-object) and a 6-axis emotional split (anger, happiness, love, sadness, share, fun: each a full summary sub-object). Sentiment is DataForSEO''s model-derived NLP, passed through verbatim, not ground truth.'
tags:
- content_analysis
operationId: get_content_analysis_sentiment
security:
- ApiKeyAuth: []
x-credit-tier: advanced
x-credit-cost: 20
parameters:
- name: keyword
in: query
required: true
description: Brand or term to analyze.
schema:
type: string
- name: page_type
in: query
required: false
description: 'Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization.'
schema:
type: string
enum:
- ecommerce
- news
- blogs
- message-boards
- organization
- name: positive_connotation_threshold
in: query
required: false
description: Minimum positive-connotation probability (0-1, default 0.4).
schema:
type: string
- name: filters
in: query
required: false
description: Advanced DataForSEO filter expression as a JSON array (≤8 conditions).
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'
/content_analysis/rating-distribution:
get:
summary: Rating histogram for a keyword
description: Returns a 10-bucket histogram (0.0-0.1 … 0.9-1.0) of the relative ratings found across web mentions of the keyword. Each bucket carries a full summary sub-object (total_count, top_domains, sentiment, categories, page types, countries, languages) so you can see how sentiment and sources vary with rating. Best for products and review-heavy terms.
tags:
- content_analysis
operationId: get_content_analysis_rating_distribution
security:
- ApiKeyAuth: []
x-credit-tier: advanced
x-credit-cost: 20
parameters:
- name: keyword
in: query
required: true
description: Product or term to build the rating histogram for.
schema:
type: string
- name: page_type
in: query
required: false
description: 'Narrow to one or more page types (comma-separated): ecommerce, news, blogs, message-boards, organization.'
schema:
type: string
enum:
- ecommerce
- news
- blogs
- message-boards
- organization
- name: filters
in: query
required: false
description: Advanced DataForSEO filter expression as a JSON array (≤8 conditions).
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'
/content_analysis/phrase-trends:
get:
summary: Keyword mention volume + sentiment over time
description: Returns a time series (one row per day
# --- truncated at 32 KB (81 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socialcrawl/refs/heads/main/openapi/socialcrawl-content-analysis-api-openapi.yml