Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: SocialCrawl Amazon 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: amazon
description: Amazon endpoints
paths:
/amazon/shop:
get:
summary: Get Amazon shop page
description: Returns product listings from an Amazon shop or storefront page including product names, prices, ratings, and images.
tags:
- amazon
operationId: get_amazon_shop
security:
- ApiKeyAuth: []
x-credit-tier: standard
x-credit-cost: 1
parameters:
- name: url
in: query
required: true
description: Full URL of the Amazon shop or storefront page
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:
id:
type: string
description: Platform-specific post ID (always a string; numeric upstream IDs are stringified)
url:
type:
- string
- 'null'
description: Direct URL to the post on the source platform
content:
type: object
description: Post content fields (text, media, thumbnail, duration)
properties:
text:
type:
- string
- 'null'
description: Post caption, description, or text content
media_urls:
type:
- string
- array
- 'null'
description: URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.
items:
type: string
description: URL(s) of the primary media. Single string for video/photo posts; array of strings for carousels.
thumbnail_url:
type:
- string
- 'null'
description: URL to thumbnail image
duration_seconds:
type:
- integer
- 'null'
description: Video/clip duration in seconds (null for non-video posts)
author:
type: object
description: Subset of Author fields for the post creator
properties:
username:
type:
- string
- 'null'
description: Author username
display_name:
type:
- string
- 'null'
description: Author display name
avatar_url:
type:
- string
- 'null'
description: URL to author profile picture
verified:
type:
- boolean
- 'null'
description: Whether the author account is verified
engagement:
type: object
description: Engagement counts
properties:
views:
type:
- integer
- 'null'
description: 'View count (if available). For Instagram video/reels this is the play count: the headline ''Views'' the IG app shows. Instagram removed per-post play counts from its public web pages in August 2026, so `GET /v1/instagram/post` now fills the count automatically from a second source within the same call: videos and reels keep a numeric `views` with no extra endpoint or workaround. Note: since mid-July 2026 Instagram''s play count is Instagram-only. It no longer includes Facebook crosspost views (Meta-side change; the app UI changed identically). For combined reach, also fetch the Facebook crosspost via `/v1/facebook/post`.'
likes:
type:
- integer
- 'null'
description: Like / reaction count
comments:
type:
- integer
- 'null'
description: 'Comment count. Note: on `GET /v1/instagram/post` this is Instagram''s `edge_media_to_parent_comment.count` (top-level comments); the IG list endpoints report the mobile `comment_count` total (includes replies). Both land on this same field.'
shares:
type:
- integer
- 'null'
description: Share / repost / retweet count. On Instagram this is `reshare_count` (the paper-plane Share / Send count) and it exists only on Instagram's mobile surface, so it is returned by `/v1/instagram/post/stats`, `/v1/instagram/profile/reels/full`, and `/v1/instagram/profile/posts/full`. The web-sourced Instagram list and search endpoints return `null` (never fabricated).
saves:
type:
- integer
- 'null'
description: 'Save / bookmark count. `null` on Instagram: the save count is platform-private and Instagram exposes no numeric save metric on any surface (never fabricated).'
flags:
type: object
description: Boolean flags on the post
properties:
nsfw:
type:
- boolean
- 'null'
description: NSFW flag (null when platform does not surface)
spoiler:
type:
- boolean
- 'null'
description: Spoiler flag (null when platform does not surface)
pinned:
type:
- boolean
- 'null'
description: Pinned-to-profile flag (null when platform does not surface)
deleted:
type: boolean
description: Whether the post is tombstoned (always present)
likes_hidden:
type:
- boolean
- 'null'
description: Present and `true` when the creator has hidden the like count. `engagement.likes` is `null` in that case (never the platform's decoy preview number). Absent on normal posts.
comments_hidden:
type:
- boolean
- 'null'
description: Present and `true` when the upstream reports the comment count as hidden. `engagement.comments` is `null` in that case. Absent on normal posts.
shares_hidden:
type:
- boolean
- 'null'
description: Boolean at post.flags.shares_hidden
views_hidden:
type:
- boolean
- 'null'
description: Boolean at post.flags.views_hidden
saves_hidden:
type:
- boolean
- 'null'
description: Boolean at post.flags.saves_hidden
published_at:
type:
- string
- integer
- 'null'
description: Post creation timestamp as an ISO 8601 UTC string. When the upstream sent a Unix epoch it is converted here and the raw epoch is preserved under `post.ext.published_at_epoch` for one deprecation cycle.
ext:
type:
- object
- 'null'
description: Platform-specific passthrough fields for cross-endpoint chains (present only on platforms that surface them)
properties:
music_id:
type:
- string
- 'null'
description: 'TikTok music/clip id (exact string): pass to `/v1/tiktok/song/videos?clipId=` to find videos using the same sound'
author_id:
type:
- string
- 'null'
description: The creator's platform-native numeric user id. On TikTok search and list items, pass to `/v1/tiktok/profile?user_id=` for the creator's current follower count (survives username changes). On Instagram `search/reels` items it is present on every row from every serving source, accepted by `/v1/instagram/basic-profile?userId=`. On Facebook it appears when the upstream exposed a numeric actor id and no real handle.
author_followers:
type:
- integer
- 'null'
description: 'The creator''s follower count as embedded in the search payload itself, when the search source happens to carry one. Historical on Instagram `search/reels`: Instagram stripped the follower count out of the search payload in August 2026, so it is now null on every Instagram row and no source can restore it. For a follower count call `/v1/instagram/profile?handle=` (1 credit, the exact current integer), or batch up to 50 creators through `POST /v1/prism/profiles`.'
subreddit:
type:
- string
- 'null'
description: 'Reddit subreddit name (search/list items): pass to `/v1/reddit/subreddit/details?subreddit=`'
title:
type:
- string
- 'null'
description: String at post.ext.title
selftext:
type:
- string
- 'null'
description: String at post.ext.selftext
type:
type:
- string
- 'null'
description: String at post.ext.type
content_type:
type:
- string
- 'null'
description: Leaf at post.ext.content_type
ticker_symbols:
type:
- array
- 'null'
description: Array at post.ext.ticker_symbols
items:
type: string
description: String at post.ext.ticker_symbols
video_view_count:
type:
- integer
- 'null'
description: 'Instagram''s legacy 3-second-view count. Historical: Instagram stopped serving it in August 2026 (removed from its web post surface along with the web play count), so fresh `/v1/instagram/post` lookups no longer carry it and no source can restore it. Use `engagement.views` (the play count) instead.'
ig_play_count:
type:
- integer
- 'null'
description: Instagram-only play count (`ig_play_count`). Since mid-July 2026 Instagram's headline play count (`engagement.views`) no longer includes Facebook crosspost views and equals this value; it is surfaced explicitly so you can tell the Instagram-only figure apart and detect any future re-divergence. For combined Instagram + Facebook reach, also fetch the Facebook crosspost via `/v1/facebook/post`. Present on `/v1/instagram/post/stats` and, since the August 2026 views fix, on `/v1/instagram/post` for video posts.
published_at_epoch:
type:
- integer
- 'null'
description: Raw Unix epoch for `published_at` (seconds, or milliseconds when the upstream sent millis). Present only when the upstream sent a numeric epoch that was normalised to the ISO 8601 `published_at` string. Kept for one deprecation cycle for integrations pinned to the numeric form.
usertags:
type:
- array
- 'null'
description: Array at post.ext.usertags
items:
type: string
description: Leaf at post.ext.usertags
coauthors:
type:
- array
- 'null'
description: Instagram collaborative posts (the native "Collab" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).
items:
type: string
description: Instagram collaborative posts (the native "Collab" feature). The full list of co-author accounts on the post, as `{ id, username, full_name, is_verified, profile_pic_url }`. A collab post has ONE producer and appears in every co-author's grid, so `post.author` is whichever account created it, which is not necessarily the profile you queried. The complete set of accounts on a post is `post.author.username` plus every `username` in this array. An empty array means Instagram reports the post as NOT a collab; the field is absent on surfaces that carry no co-author signal, including `/v1/instagram/post` (its web source ships the field permanently empty, so use `/v1/instagram/post/stats` for a single post).
music:
type:
- string
- 'null'
description: Leaf at post.ext.music
sponsor_tags:
type:
- array
- 'null'
description: Array at post.ext.sponsor_tags
items:
type: string
description: Leaf at post.ext.sponsor_tags
location:
type:
- string
- 'null'
description: Leaf at post.ext.location
reaction_counts:
type:
- array
- 'null'
description: Array at post.ext.reaction_counts
items:
type: string
description: Leaf at post.ext.reaction_counts
share_urn:
type:
- string
- 'null'
description: String at post.ext.share_urn
post_type:
type:
- string
- 'null'
description: String at post.ext.post_type
download_media_urls:
type:
- array
- 'null'
description: Array at post.ext.download_media_urls
items:
type: string
description: Leaf at post.ext.download_media_urls
tags:
type:
- array
- 'null'
description: Array at post.ext.tags
items:
type: string
description: String at post.ext.tags
categoryId:
type:
- string
- 'null'
description: String at post.ext.categoryId
categoryTitle:
type:
- string
- 'null'
description: String at post.ext.categoryTitle
topicCategories:
type:
- array
- 'null'
description: Array at post.ext.topicCategories
items:
type: string
description: String at post.ext.topicCategories
duration:
type:
- string
- 'null'
description: String at post.ext.duration
license:
type:
- string
- 'null'
description: String at post.ext.license
madeForKids:
type:
- boolean
- 'null'
description: Boolean at post.ext.madeForKids
defaultAudioLanguage:
type:
- string
- 'null'
description: String at post.ext.defaultAudioLanguage
hasPaidProductPlacement:
type:
- boolean
- 'null'
description: Boolean at post.ext.hasPaidProductPlacement
caption:
type:
- string
- 'null'
description: String at post.ext.caption
position:
type:
- integer
- 'null'
description: Numeric at post.ext.position
playlistId:
type:
- string
- 'null'
description: String at post.ext.playlistId
videoOwnerChannelId:
type:
- string
- 'null'
description: String at post.ext.videoOwnerChannelId
videoPublishedAt:
type:
- string
- 'null'
description: String at post.ext.videoPublishedAt
description:
type:
- string
- 'null'
description: String at post.ext.description
default_language:
type:
- string
- 'null'
description: String at post.ext.default_language
playlist_item_id:
type:
- string
- 'null'
description: String at post.ext.playlist_item_id
playlist_owner_channel_id:
type:
- string
- 'null'
description: String at post.ext.playlist_owner_channel_id
playlist_owner_title:
type:
- string
- 'null'
description: String at post.ext.playlist_owner_title
channel_id:
type:
- string
- 'null'
description: String at post.ext.channel_id
video_count:
type:
- integer
- 'null'
description: Numeric at post.ext.video_count
commerce:
type:
- string
- 'null'
description: Leaf at post.ext.commerce
on_screen_texts:
type:
- array
- 'null'
description: Array at post.ext.on_screen_texts
items:
type: string
description: String at post.ext.on_screen_texts
topic_tag:
type:
- string
- 'null'
description: String at post.ext.topic_tag
topic_tag_id:
type:
- string
- 'null'
description: String at post.ext.topic_tag_id
amazon_shop_lists:
type:
- array
- 'null'
description: Array at post.ext.amazon_shop_lists
items:
type: string
description: Leaf at post.ext.amazon_shop_lists
amazon_shop_trending_picks:
type:
- array
- 'null'
description: Array at post.ext.amazon_shop_trending_picks
items:
type: string
description: Leaf at post.ext.amazon_shop_trending_picks
amazon_shop_curations:
type:
- array
- 'null'
description: Array at post.ext.amazon_shop_curations
items:
type: string
description: Leaf at post.ext.amazon_shop_curations
amazon_shop_socials:
type:
- array
- 'null'
description: Array at post.ext.amazon_shop_socials
items:
type: string
description: String at post.ext.amazon_shop_socials
ad:
type:
- string
- 'null'
description: 'Ad Library envelope (Facebook `adlibrary/ad` and `adlibrary/company/ads` items): page_id, currency, spend, reach_estimate, publisher_platforms, categories, targeted_or_reached_countries, cta_text, cta_type, link_url, is_active, end_date_iso, display_format, title, video_hd_url, video_sd_url. Absent on every non-ad surface.'
apple_music:
type:
- string
- 'null'
description: Leaf at post.ext.apple_music
_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'
/amazon/product-search:
get:
summary: Search Amazon products by keyword
description: 'Returns organic Amazon search results for a keyword: title, price, list price, rating, image, and ASIN per product. Results reflect the chosen marketplace (default United States). Sponsored placements and related searches are excluded in v1. Paginate with the universal cursor parameter; pass depth instead if you need a single large page.'
tags:
- amazon
operationId: get_amazon_product_search
security:
- ApiKeyAuth: []
x-credit-tier: standard
x-credit-cost: 1
parameters:
- name: query
in: query
required: true
description: Search keyword or phrase.
schema:
type: string
- name: country
in: query
required: false
description: 'Amazon marketplace as an ISO 3166-1 alpha-2 country code (default US). Supported: US, GB, CA, DE, FR, IT, ES, JP, IN, MX, BR, AU, NL. Non-US marketplaces are best-effort; an occasional timeout is refunded.'
schema:
type: string
enum:
# --- truncated at 32 KB (117 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socialcrawl/refs/heads/main/openapi/socialcrawl-amazon-api-openapi.yml