Skip to content
truescrape/api
Get an API key

Reference

API reference

Generated from the live spec at /openapi.json, so what is printed here is what the server serves. Every operation publishes its price as x-credit-cost.

Endpoints

173

Platforms

28

Cacheable

173

hits cost 0 credits

Batchable

168

usable in /v1/jobs/batch

Amazon

GET/v1/amazon/shop1 creditcacheablebatchableneeds proxies

Amazon Shop page

A creator's public Amazon storefront: their name, and the product links the page exposes.

ParameterTypeRequiredDescription
urlstringyesStorefront URL (https://www.amazon.com/shop/<handle>) or just the handle

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/amazon/shop?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/amazon/shop?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/amazon/shop",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Apple-music

GET/v1/apple-music/album1 creditcacheablebatchable

Album details

Public Apple Music album: artist, release date, genre, copyright, artwork and total runtime. The full track listing is in raw — add include_raw=true.

ParameterTypeRequiredDescription
idstringyesApple Music album id (1708308989) or a music.apple.com album URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/apple-music/album?id=%3Cid%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  id: '<id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/apple-music/album?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/apple-music/album",
    params={
        "id": "<id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/apple-music/artist1 creditcacheablebatchable

Artist details

Public Apple Music artist page: editorial bio, artist image and genre. Apple publishes no follower or play counts, so those fields are null rather than guessed.

ParameterTypeRequiredDescription
idstringyesApple Music artist id (159260351) or a music.apple.com artist URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/apple-music/artist?id=%3Cid%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  id: '<id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/apple-music/artist?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/apple-music/artist",
    params={
        "id": "<id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/apple-music/track1 creditcacheablebatchable

Track details

Public Apple Music track: artist, album, duration, genre, release date and the 30-second preview URL.

ParameterTypeRequiredDescription
idstringyesApple Music track id (1833328840), a /song/ URL, or an album URL with ?i=<track id>

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/apple-music/track?id=%3Cid%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  id: '<id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/apple-music/track?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/apple-music/track",
    params={
        "id": "<id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Bluesky

GET/v1/bluesky/post1 creditcacheablebatchable

Post

A single public Bluesky post with like, reply, repost and quote counts, plus any attached images or video.

ParameterTypeRequiredDescription
urlstringyesPost URL (https://bsky.app/profile/<handle>/post/<id>) or an at:// URI

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/bluesky/post?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/bluesky/post?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/bluesky/post",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/bluesky/profile1 creditcacheablebatchable

Profile

Public profile for a Bluesky account: followers, following, post count, bio, avatar, banner, and verification status.

ParameterTypeRequiredDescription
handlestringyesHandle (alice.bsky.social), a did:plc:… identifier, or a bsky.app profile URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/bluesky/profile?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/bluesky/profile?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/bluesky/profile",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/bluesky/user/posts1 creditcacheablebatchable

User posts

Recent public posts from a Bluesky account, newest first. Reposts are excluded by default so the feed reflects what the account actually wrote.

ParameterTypeRequiredDescription
handlestringyesHandle, did, or bsky.app profile URL
countnumbernodefaults to 50
cursorstringnopagination.cursor from a previous response
include_repostsbooleannoInclude reposts of other accounts. Default false.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/bluesky/user/posts?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/bluesky/user/posts?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/bluesky/user/posts",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Facebook

GET/v1/facebook/ad-library/ad1 creditcacheablebatchable

Ad details

One ad from the Meta Ad Library by its archive id. Meta does not expose the archive as an addressable node for every ad; pass page_id as well and we find it by scanning that advertiser's archive instead.

ParameterTypeRequiredDescription
idstringyesAd archive id, or an Ad Library URL containing ?id=
page_idstringnoThe advertiser's page id. Enables the archive-scan fallback.
countrystringnoReached country used by the fallback scandefaults to US

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/ad-library/ad?id=%3Cid%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  id: '<id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/ad-library/ad?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/ad-library/ad",
    params={
        "id": "<id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/ad-library/advertisers1 creditcacheablebatchable

Find advertisers running ads

Distinct advertisers whose ads match a search term, with the page_id needed by /v1/facebook/ad-library/page-ads. Derived from the official Ad Library search — Meta has no advertiser-search endpoint of its own.

ParameterTypeRequiredDescription
querystringyesAdvertiser name or a term from their ad copy
countrystringnodefaults to US
statusactive | inactive | allnodefaults to active
limitnumbernoAds sampled, 1-100. More ads means more advertisers.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/ad-library/advertisers?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/ad-library/advertisers?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/ad-library/advertisers",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/ad-library/page-ads2 creditscacheablebatchable

All ads for one advertiser

Every ad a specific Facebook page is running or has run, from Meta's official Ad Library API. This is the competitor-monitoring endpoint: page it with cursor to pull a full creative history.

ParameterTypeRequiredDescription
page_idstringyesNumeric page id, or an Ad Library URL containing view_all_page_id
countrystringnoISO-3166 country code(s) the ad reached, comma-separated. Meta requires at least one.defaults to US
statusactive | inactive | allnoDelivery status at the time of the query.defaults to active
ad_typeall | political | housing | employment | creditnopolitical unlocks Meta's spend, impression and demographic fields.defaults to all
media_typeall | image | meme | video | noneno—
platformstringnoComma-separated: facebook, instagram, messenger, audience_network, threads, whatsapp, oculus
languagestringnoComma-separated BCP-47 codes, e.g. "en,es"
start_datestringnoEarliest delivery date, YYYY-MM-DD
end_datestringnoLatest delivery date, YYYY-MM-DD
limitnumbernoAds per page, 1-100. Default 25.
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/ad-library/page-ads?page_id=%3Cpage_id%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  page_id: '<page_id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/ad-library/page-ads?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 2 credits, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/ad-library/page-ads",
    params={
        "page_id": "<page_id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/ad-library/search2 creditscacheablebatchable

Search the Meta Ad Library

Every Facebook, Instagram, Messenger and Threads ad matching a search term, from Meta's official Ad Library API. Political and issue ads additionally carry spend and impression ranges.

ParameterTypeRequiredDescription
querystringyesSearch term, matched against ad text and advertiser name
search_typeunordered | exact_phrasenoexact_phrase matches the words in orderdefaults to unordered
countrystringnoISO-3166 country code(s) the ad reached, comma-separated. Meta requires at least one.defaults to US
statusactive | inactive | allnoDelivery status at the time of the query.defaults to active
ad_typeall | political | housing | employment | creditnopolitical unlocks Meta's spend, impression and demographic fields.defaults to all
media_typeall | image | meme | video | noneno—
platformstringnoComma-separated: facebook, instagram, messenger, audience_network, threads, whatsapp, oculus
languagestringnoComma-separated BCP-47 codes, e.g. "en,es"
start_datestringnoEarliest delivery date, YYYY-MM-DD
end_datestringnoLatest delivery date, YYYY-MM-DD
limitnumbernoAds per page, 1-100. Default 25.
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/ad-library/search?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/ad-library/search?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 2 credits, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/ad-library/search",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/comment-replies1 creditcacheablebatchableneeds proxies

Replies to a comment

Replies under one comment on a public Facebook post. Pass the post URL and the comment id (the id of any item from /v1/facebook/post-comments).

ParameterTypeRequiredDescription
urlstringyesFull post URL the comment sits on
comment_idstringyesNumeric comment id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/comment-replies?url=8XkPqR2nLvE&comment_id=%3Ccomment_id%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  comment_id: '<comment_id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/comment-replies?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/comment-replies",
    params={
        "url": "8XkPqR2nLvE",
        "comment_id": "<comment_id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/event1 creditcacheablebatchableneeds proxies

Event details

Full details for one public Facebook event: description, start and end time, venue with coordinates, host and ticket price range.

ParameterTypeRequiredDescription
urlstringyesEvent URL or numeric event id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/event?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/event?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/event",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/events/search1 creditcacheablebatchableneeds proxies

Search public events

Public Facebook events matching a search term. Results are ranked and location-biased by the exit IP, so the same query returns a different set from a different proxy — treat this as discovery, not as an enumerable list.

ParameterTypeRequiredDescription
querystringyesWhat to search for, e.g. "jazz festival"

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/events/search?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/events/search?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/events/search",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/group1 creditcacheablebatchableneeds proxies

Public group info

Name, member count, privacy setting and description for a public Facebook group. Member count lands in followerCount — it is a group's equivalent of an audience size — and the privacy setting in category. Facebook rounds that count on large groups ("12K members"); raw.memberCountIsApproximate says whether the number you got was rounded.

ParameterTypeRequiredDescription
urlstringyesGroup URL, group id, or group slug

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/group?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/group?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/group",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/group-posts1 creditcacheablebatchableneeds proxies

Public group posts

Recent posts from a public Facebook group, with reaction, comment and share counts where Facebook renders them. Only the newest few stories render to a logged-out visitor, the same limit /v1/facebook/page-posts has. Private groups return an empty result — their posts are not public and we do not log in.

ParameterTypeRequiredDescription
urlstringyesGroup URL, group id, or group slug

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/group-posts?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/group-posts?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/group-posts",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/marketplace/item1 creditcacheablebatchableneeds proxies

Marketplace listing details

One public Facebook Marketplace listing: title, full description, price, location, delivery options and every photo. Facebook does not render the seller to a logged-out visitor, so seller identity is not returned.

ParameterTypeRequiredDescription
urlstringyesMarketplace item URL or numeric listing id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/marketplace/item?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/marketplace/item?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/marketplace/item",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/marketplace/locations1 creditcacheablebatchableneeds proxies

Find a Marketplace location

Resolve a place name to the Marketplace location ids /v1/facebook/marketplace/search accepts, plus the neighbouring locations Facebook offers around it. Marketplace is city-scoped, so this is how you search a city you are not sitting in.

ParameterTypeRequiredDescription
querystringyesPlace name, e.g. "London" or "San Francisco"

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/marketplace/locations?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/marketplace/locations?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/marketplace/locations",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/marketplace/search1 creditcacheablebatchableneeds proxies

Search Marketplace listings

Public Facebook Marketplace listings matching a search term, with price, condition flags, location and photos. location takes a city slug or a location id from /v1/facebook/marketplace/locations; without one, Facebook picks the city its geolocation puts the request in, which means the proxy decides.

ParameterTypeRequiredDescription
querystringyesWhat to search for, e.g. "mountain bike"
locationstringnoCity slug ("nyc", "london") or a location id from /v1/facebook/marketplace/locations
min_pricenumbernoLowest price, in the location's currency
max_pricenumbernoHighest price, in the location's currency
days_since_listednumbernoOnly listings posted in the last N days
radius_kmnumbernoSearch radius around the location, in kilometres
sort_bybest_match | creation_time_descend | price_ascend | price_descend | distance_ascendnoFacebook's own sort keys
delivery_methodlocal_pick_up | shippingnoRestrict to collection-only or shipped listings

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/marketplace/search?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/marketplace/search?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/marketplace/search",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/page-posts1 creditcacheablebatchableneeds proxies

Public Page posts

Recent public posts from a Facebook Page, with text, reaction, comment and share counts, and the publish timestamp. Logged out, Facebook server-renders only the newest one to three stories and loads the rest on scroll behind an authenticated call — measured 2026-08-20 across four different Page URL shapes — so this returns the head of the feed, not its history. raw.hasMoreBehindCursor reports whether Facebook says there is more.

ParameterTypeRequiredDescription
urlstringyesPage URL, @handle, slug, or numeric page id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/page-posts?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/page-posts?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/page-posts",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/page-reels1 creditcacheablebatchableneeds proxies

Public Page videos and reels

Public videos and reels from a Facebook Page. Reads the Page's reels tab first and falls back to its video grid, which renders around twenty entries with titles, view counts and durations — so a Page with no reels returns its videos rather than an error. Items are keyed by video id and can be passed straight to /v1/facebook/post or /v1/facebook/post-transcript.

ParameterTypeRequiredDescription
urlstringyesPage URL, @handle, slug, or numeric page id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/page-reels?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/page-reels?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/page-reels",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/post1 creditcacheablebatchableneeds proxies

Single post, video, or reel

One public Facebook post, video or reel by URL, with its text and engagement counts.

ParameterTypeRequiredDescription
urlstringyesFull post, video, or reel URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/post?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/post?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/post",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/post-comments1 creditcacheablebatchableneeds proxies

Comments on a post

Top-level comments on a public Facebook post, with author, reaction count and reply count. Logged out, Facebook renders the "Most relevant" head of the thread (roughly the first ten comments) rather than the whole thread — the post's full comment total is on /v1/facebook/post. Use /v1/facebook/comment-replies for the replies under one comment. likeCount is only as precise as Facebook publishes it: comment reactions ship in abbreviated form ("2.4K") with no exact figure anywhere in the payload, so counts above about a thousand are rounded at source.

ParameterTypeRequiredDescription
urlstringyesFull post, video, or reel URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/post-comments?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/post-comments?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/post-comments",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/post-transcript1 creditcacheablebatchableneeds proxies

Video transcript

Transcript for a public Facebook video or reel, as one text block plus timed cues. Reads the caption track Facebook publishes for the video — auto-generated when the uploader added none. Videos with captions disabled return an empty result and are not charged.

ParameterTypeRequiredDescription
urlstringyesFull video or reel URL
languagestringnoPreferred caption locale, e.g. "en" or "en_US"

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/post-transcript?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/post-transcript?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/post-transcript",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/profile1 creditcacheablebatchableneeds proxies

Public Page profile

Name, category, follower and like counts, description, banner and outbound links for a public Facebook Page. followerCount is as precise as Facebook renders it — exact on a small Page ("498 followers"), rounded on a large one ("28M followers", so ±500,000). raw.followerCountIsApproximate says which you got, and raw.likeCount carries the exact like figure Facebook always prints.

ParameterTypeRequiredDescription
urlstringyesPage URL, @handle, slug, or numeric page id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/profile?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/profile?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/profile",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/profile-events1 creditcacheablebatchableneeds proxies

Events on a Page

Events hosted by a public Facebook Page — upcoming ones first, with past events where Facebook still lists them. Each carries start time, place, host and the cover photo.

ParameterTypeRequiredDescription
urlstringyesPage URL, @handle, slug, or numeric page id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/profile-events?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/profile-events?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/profile-events",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/facebook/profile-photos1 creditcacheablebatchableneeds proxies

Photos on a Page

Photos from a public Facebook Page's photo grid. Facebook exposes each photo's accessibility caption rather than the text of the post it came from, so that is what lands in title.

ParameterTypeRequiredDescription
urlstringyesPage URL, @handle, slug, or numeric page id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/facebook/profile-photos?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/profile-photos?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/profile-photos",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Github

GET/v1/github/repository1 creditcacheablebatchable

Repository details

Public details for a repository: stars, forks, open issues, topics, language and licence. Stars map to likeCount, forks to shareCount.

ParameterTypeRequiredDescription
urlstringyes"owner/repo" or a github.com repository URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/github/repository?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/github/repository?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/github/repository",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/github/trending/developers1 creditcacheable

Trending developers

The public github.com/trending/developers board. Counts are null: the board renders names and popular repositories, not follower numbers.

ParameterTypeRequiredDescription
languagestringnoLanguage slug, e.g. "rust"
sincedaily | weekly | monthlynodefaults to daily

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/github/trending/developers?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/github/trending/developers?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/github/trending/developers",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/github/trending/repositories1 creditcacheable

Trending repositories

The public github.com/trending board. likeCount is total stars and shareCount total forks; the stars gained in the period are in raw.

ParameterTypeRequiredDescription
languagestringnoLanguage slug, e.g. "typescript"
sincedaily | weekly | monthlynodefaults to daily
spoken_language_codestringnoTwo-letter code, e.g. "en"

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/github/trending/repositories?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/github/trending/repositories?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/github/trending/repositories",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/github/user1 creditcacheablebatchable

User or organisation profile

Public profile for a GitHub user or organisation: followers, public repo count, bio, company, location and links. **Required:** Pass either handle or url.

ParameterTypeRequiredDescription
handlestringnoUsername, e.g. "torvalds"
urlstringnoProfile URL, e.g. https://github.com/torvalds

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/github/user?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/github/user?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/github/user",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/github/user/activity1 creditcacheablebatchable

Public activity

Public events for a user — pushes, pull requests, issues, stars, forks and releases. GitHub caps this feed at 300 events / 90 days regardless of paging. **Required:** Pass either handle or url.

ParameterTypeRequiredDescription
handlestringnoUsername, e.g. "torvalds"
urlstringnoProfile URL, e.g. https://github.com/torvalds
cursorstringnoPage number from the previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/github/user/activity?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/github/user/activity?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/github/user/activity",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/github/user/contributions1 creditcacheablebatchable

Contributions calendar

The contribution graph for one calendar year: a per-day count plus GitHub's 0–4 intensity level, and the annual total. **Required:** Pass either handle or url.

ParameterTypeRequiredDescription
handlestringnoUsername, e.g. "torvalds"
urlstringnoProfile URL, e.g. https://github.com/torvalds
yearstringnoCalendar year, e.g. "2025". Defaults to the current year.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/github/user/contributions?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/github/user/contributions?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/github/user/contributions",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/github/user/followers1 creditcacheablebatchable

Followers

Accounts following this user, 30 per page. GitHub serves a reduced user payload here, so per-account counts are null. **Required:** Pass either handle or url.

ParameterTypeRequiredDescription
handlestringnoUsername, e.g. "torvalds"
urlstringnoProfile URL, e.g. https://github.com/torvalds
cursorstringnoPage number from the previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/github/user/followers?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/github/user/followers?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/github/user/followers",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/github/user/following1 creditcacheablebatchable

Following

Accounts this user follows, 30 per page. GitHub serves a reduced user payload here, so per-account counts are null. **Required:** Pass either handle or url.

ParameterTypeRequiredDescription
handlestringnoUsername, e.g. "torvalds"
urlstringnoProfile URL, e.g. https://github.com/torvalds
cursorstringnoPage number from the previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/github/user/following?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/github/user/following?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/github/user/following",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/github/user/pull-requests1 creditcacheablebatchable

Pull requests by a user

Pull requests authored by a user across all public repositories, newest first. since / until filter on creation date.

ParameterTypeRequiredDescription
handlestringyesUsername, e.g. "gaearon"
sincestringnoOnly PRs created on or after this date (YYYY-MM-DD)
untilstringnoOnly PRs created on or before this date (YYYY-MM-DD)
cursorstringnoPage number from the previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/github/user/pull-requests?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/github/user/pull-requests?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/github/user/pull-requests",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/github/user/repositories1 creditcacheablebatchable

User repositories

Public repositories owned by a user or organisation, 30 per page. **Required:** Pass either handle or url.

ParameterTypeRequiredDescription
handlestringnoUsername, e.g. "torvalds"
urlstringnoProfile URL, e.g. https://github.com/torvalds
typeall | owner | membernodefaults to owner
sortcreated | updated | pushed | full_namenodefaults to updated
directionasc | descnodefaults to desc
cursorstringnoPage number from the previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/github/user/repositories?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/github/user/repositories?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/github/user/repositories",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Google

GET/v1/google/ad-library/advertiser-ads2 creditscacheablebatchable

Ads run by an advertiser or domain

Creatives in the Ads Transparency Centre for one advertiser id or one verified domain, with first-shown and last-shown dates. Pass the cursor from the previous response to page. **Required:** Pass either domain or advertiser_id.

ParameterTypeRequiredDescription
domainstringnoVerified advertiser domain, e.g. "nike.com"
advertiser_idstringnoAdvertiser id from /ad-library/advertisers, e.g. "AR167..."
regionstringnoTwo-letter country code (US, GB, DE, IN, ...) or a Google geo criteria iddefaults to US
cursorstringnoContinuation token from the previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/google/ad-library/advertiser-ads?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/google/ad-library/advertiser-ads?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 2 credits, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/google/ad-library/advertiser-ads",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/google/ad-library/advertisers1 creditcacheablebatchable

Find advertisers in the Ads Transparency Centre

Advertisers matching a name, with the advertiser id that /v1/google/ad-library/advertiser-ads needs, plus the verified domains Google suggests for the same term.

ParameterTypeRequiredDescription
querystringyesAdvertiser or brand name, e.g. "nike"
regionstringnoTwo-letter country code (US, GB, DE, IN, ...) or a Google geo criteria iddefaults to US

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/google/ad-library/advertisers?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/google/ad-library/advertisers?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/google/ad-library/advertisers",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Inference

GET/v1/detect-age-gender1 creditcacheablebatchableexperimental

Estimate age and gender from an image

Apparent age and gender estimated from a public image URL. This is a model ESTIMATE, not measured platform data, and every response is labelled as such. Requires an inference provider to be configured on the deployment.

ParameterTypeRequiredDescription
urlstringyesPublic image URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/detect-age-gender?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/detect-age-gender?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/detect-age-gender",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Instagram

GET/v1/instagram/audio-reels1 creditcacheablebatchableneeds proxiesexperimental

Reels using a sound

Reels built on one audio track — the "N reels using this audio" list. Takes the numeric audio id or a /reels/audio/ URL. Falls back to the server-rendered audio page, which returns the first grid only.

ParameterTypeRequiredDescription
audio_idstringyesNumeric audio id, or a /reels/audio/<id>/ URL
cursorstringnopagination.cursor from a previous response
countnumbernoReels per page, 1-50. Default 12.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/audio-reels?audio_id=%3Caudio_id%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  audio_id: '<audio_id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/audio-reels?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/audio-reels",
    params={
        "audio_id": "<audio_id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/basic-profile1 creditcacheablebatchableneeds proxiesexperimental

Profile by numeric id

The lightweight profile payload, addressed by numeric user id. Use this when you already hold an id — it skips the handle lookup and returns a smaller object than /v1/instagram/profile, which stays the right call when you have a handle and want everything. **Required:** Pass either handle or user_id.

ParameterTypeRequiredDescription
handlestringnoHandle (@nike), or a full instagram.com profile URL. Optional if user_id is given.
user_idstringnoNumeric user id. Skips a lookup — take it from data.items[].authorId.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/basic-profile?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/basic-profile?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/basic-profile",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/comment-replies1 creditcacheableneeds proxiesexperimental

Replies under one comment

The full reply thread under a single comment. Take comment_id from data.items[].id on /v1/instagram/post-comments; the post URL is still required because Instagram addresses replies through the media that carries them.

ParameterTypeRequiredDescription
urlstringyesPost, reel or IGTV URL, or a bare shortcode
comment_idstringyesdata.items[].id from /v1/instagram/post-comments
cursorstringnopagination.cursor from a previous response
countnumbernoReplies per page, 1-50. Default 24.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/comment-replies?url=8XkPqR2nLvE&comment_id=%3Ccomment_id%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  comment_id: '<comment_id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/comment-replies?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/comment-replies",
    params={
        "url": "8XkPqR2nLvE",
        "comment_id": "<comment_id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/hashtag-posts1 creditcacheablebatchableneeds proxiesexperimental

Posts under a hashtag

Posts carrying a hashtag. tab=top is Instagram's ranking (one fixed page, no cursor); tab=recent is chronological and paginates. Falls back to the server-rendered tag page when the JSON surface declines, which returns the top grid only.

ParameterTypeRequiredDescription
hashtagstringyesHashtag (#nasa or nasa), or an /explore/tags/ URL
tabtop | recentnoInstagram's ranking, or chronologicaldefaults to top
cursorstringnopagination.cursor from a previous response — recent only

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/hashtag-posts?hashtag=%3Chashtag%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  hashtag: '<hashtag>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/hashtag-posts?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/hashtag-posts",
    params={
        "hashtag": "<hashtag>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/highlight1 creditcacheablebatchableneeds proxiesexperimental

Stories inside a highlight

Every story in one highlight reel, oldest first, with its media URLs. Takes the id from /v1/instagram/user-highlights, a bare numeric id, or a /stories/highlights/ URL.

ParameterTypeRequiredDescription
idstringyesHighlight id ("highlight:17…" or the bare number), or a /stories/highlights/ URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/highlight?id=%3Cid%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  id: '<id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/highlight?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/highlight",
    params={
        "id": "<id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/popular-search1 creditcacheablebatchableneeds proxiesexperimental

Top posts for a keyword

Instagram's keyword results across every media type — reels, images and carousels together. The same surface as /v1/instagram/reels-search without the clips filter.

ParameterTypeRequiredDescription
querystringyesKeyword to search for
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/popular-search?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/popular-search?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/popular-search",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/post1 creditcacheablebatchableneeds proxiesexperimental

Post or reel details

One public post, reel or carousel with its caption, media URLs and engagement counts. Falls back to Instagram's public embed payload when the web client's persisted query is unavailable, so a Meta client release degrades this rather than breaking it.

ParameterTypeRequiredDescription
urlstringyesPost, reel or IGTV URL, or a bare shortcode

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/post?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/post?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/post",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/post-comments1 creditcacheablebatchableneeds proxiesexperimental

Comments on a post or reel

Top-level comments, newest first. Set include_replies=true to also return any replies Instagram shipped inline with their parent — for the full reply thread under one comment, use /v1/instagram/comment-replies.

ParameterTypeRequiredDescription
urlstringyesPost, reel or IGTV URL, or a bare shortcode
cursorstringnopagination.cursor from a previous response
countnumbernoComments per page, 1-50. Default 24.
include_repliesbooleannoInclude replies that arrived inline with their parent comment

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/post-comments?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/post-comments?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/post-comments",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/profile1 creditcacheablebatchableneeds proxiesexperimental

Profile details

Public profile for an Instagram account: followers, following, post count, bio, links and business category. Private accounts return their public shell with isPrivate: true rather than an error — that is a real answer.

ParameterTypeRequiredDescription
handlestringyesHandle (@nike), or a full instagram.com profile URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/profile?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/profile?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/profile",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/profile-search1 creditcacheablebatchableneeds proxiesexperimental

Search accounts

Accounts matching a query, as unified Creators. The follower counts on a search result are Instagram's own summary and are thinner than /v1/instagram/profile — fetch that for one account you care about. One page only; this surface has no cursor.

ParameterTypeRequiredDescription
querystringyesHandle or name to search for

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/profile-search?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/profile-search?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/profile-search",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/reels-search1 creditcacheablebatchableneeds proxiesexperimental

Search reels by keyword

Reels matching a keyword, from Instagram's own keyword search rather than its hashtag index — the two return genuinely different sets, so this never quietly substitutes one for the other. Results are whatever Instagram ranked for the query at that moment.

ParameterTypeRequiredDescription
querystringyesKeyword to search for
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/reels-search?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/reels-search?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/reels-search",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/transcript1 creditcacheablebatchableneeds proxiesexperimental

Reel or video transcript

The caption track Instagram published for a reel or video, as one text block plus timed cues. We return Instagram's own track and never transcribe the audio ourselves, so a transcript here is always what the platform said rather than what a model guessed. **Read this before relying on it:** checked against 12 real reel payloads, none carried a caption track in any form — no inline transcript, and DASH manifests with video and audio tracks only. On current evidence Instagram publishes none, so this returns empty_result (free, never charged) rather than a transcript. It is shipped as experimental so the shape is stable if that changes.

ParameterTypeRequiredDescription
urlstringyesReel, post or IGTV URL, or a bare shortcode

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/transcript?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/transcript?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/transcript",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/trending-reels1 creditcacheableneeds proxiesexperimental

Reels trending on Explore

Reels off Instagram's public Explore grid. Worth knowing what this is and is not: Explore is region-shaped, so what comes back depends on where the request exits, and it is Instagram's editorial surface rather than a global chart. There is no public trending feed on Instagram; this is the closest one that exists.

ParameterTypeRequiredDescription
cursorstringnopagination.cursor from a previous response
countnumbernoReels per page, 1-50. Default 24.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/trending-reels?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/trending-reels?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/trending-reels",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/user-embed1 creditcacheablebatchableneeds proxiesexperimental

Profile via the public embed card

A profile read off Instagram's public embed card, with the embed HTML in raw.html for anyone who wants to render it. Instagram publishes embeds so third parties can display them, which makes this the profile path it has the least reason to gate — the same reasoning that puts the post embed on /v1/instagram/post's fallback. It carries fewer fields than /v1/instagram/profile; reach for it when that one is blocked, or when you want the markup.

ParameterTypeRequiredDescription
handlestringyesHandle (@nike), or a full instagram.com profile URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/user-embed?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/user-embed?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/user-embed",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/user-highlights1 creditcacheablebatchableneeds proxiesexperimental

Story highlight covers

The highlight reels pinned to a profile: title, cover, and how many stories each holds. Pass an id from here to /v1/instagram/highlight for the stories inside one. Highlights are the only Instagram stories that stay public indefinitely — live stories expire in 24 hours and are not served logged-out. **Required:** Pass either handle or user_id.

ParameterTypeRequiredDescription
handlestringnoHandle (@nike), or a full instagram.com profile URL. Optional if user_id is given.
user_idstringnoNumeric user id. Skips a lookup — take it from data.items[].authorId.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/user-highlights?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/user-highlights?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/user-highlights",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/user-posts1 creditcacheablebatchableneeds proxiesexperimental

Posts and reels from a profile

A profile grid, newest first. The first page comes from the same payload as the profile and is the reliable one; pass cursor (and ideally user_id) for older pages, which Instagram serves far less consistently to logged-out callers.

ParameterTypeRequiredDescription
handlestringyesHandle (@nike), or a full instagram.com profile URL
cursorstringnopagination.cursor from a previous response
user_idstringnoNumeric user id. Saves a round trip when paginating; take it from data.items[].authorId.
countnumbernoPosts per page when paginating, 1-50. Default 12.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/user-posts?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/user-posts?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/user-posts",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/user-reels1 creditcacheablebatchableneeds proxiesexperimental

Reels from a profile

A profile's reels, newest first. Primary path is the reels tab's own feed; if Instagram declines it, this falls back to filtering the profile grid down to clips, so the endpoint degrades in density rather than going dark. raw.via says which answered. **Required:** Pass either handle or user_id.

ParameterTypeRequiredDescription
handlestringnoHandle (@nike), or a full instagram.com profile URL. Optional if user_id is given.
user_idstringnoNumeric user id. Skips a lookup — take it from data.items[].authorId.
cursorstringnopagination.cursor from a previous response
countnumbernoReels per page, 1-50. Default 12.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/user-reels?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/user-reels?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/user-reels",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/instagram/user-tagged-posts1 creditcacheablebatchableneeds proxiesexperimental

Posts a profile is tagged in

Public posts by other accounts that tagged this user — the "Tagged" tab. Note this is other people's content: authorHandle is the poster, not the tagged account. Users can hide the tab, which returns empty_result. **Required:** Pass either handle or user_id.

ParameterTypeRequiredDescription
handlestringnoHandle (@nike), or a full instagram.com profile URL. Optional if user_id is given.
user_idstringnoNumeric user id. Skips a lookup — take it from data.items[].authorId.
cursorstringnopagination.cursor from a previous response
countnumbernoPosts per page, 1-50. Default 12.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/instagram/user-tagged-posts?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/instagram/user-tagged-posts?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/instagram/user-tagged-posts",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Kick

GET/v1/kick/clip1 creditcacheablebatchableneeds proxies

Clip

A public Kick clip: title, creator, channel, duration, view count, and media URL.

ParameterTypeRequiredDescription
urlstringyesClip URL (https://kick.com/<channel>?clip=clip_XXXX or /clips/clip_XXXX) or a clip id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/kick/clip?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/kick/clip?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/kick/clip",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Komi

GET/v1/komi1 creditcacheablebatchable

Komi page

Public Komi page as a creator profile: display name, bio, avatar, and every outbound link in order.

ParameterTypeRequiredDescription
urlstringyesPage URL (https://komi.io/<username>) or just the username

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/komi?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/komi?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/komi",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Kwai

GET/v1/kwai/post1 creditcacheablebatchable

Post

A single public Kwai video with its view, like, comment and forward counts.

ParameterTypeRequiredDescription
urlstringyesVideo URL (https://www.kwai.com/@<handle>/video/<photo_id>)

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/kwai/post?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/kwai/post?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/kwai/post",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/kwai/profile1 creditcacheablebatchable

Profile

Public Kwai profile: follower and following counts, public video count, bio, avatar, and creator category.

ParameterTypeRequiredDescription
handlestringyesHandle (@carlinhos) or a kwai.com profile URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/kwai/profile?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/kwai/profile?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/kwai/profile",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/kwai/user/posts1 creditcacheablebatchable

User posts

Recent public videos from a Kwai profile, with view, like, comment and forward counts.

ParameterTypeRequiredDescription
handlestringyesHandle (@carlinhos) or a kwai.com profile URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/kwai/user/posts?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/kwai/user/posts?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/kwai/user/posts",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Linkbio

GET/v1/linkbio1 creditcacheablebatchable

Lnk.Bio page

Public Lnk.Bio page as a creator profile: display name, bio, avatar, and every outbound link in order.

ParameterTypeRequiredDescription
urlstringyesPage URL (https://lnk.bio/<username>) or just the username

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/linkbio?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/linkbio?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/linkbio",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

LinkedIn

GET/v1/linkedin/ad1 creditcacheablebatchable

Ad details

One ad from LinkedIn's public Ad Library: creative, copy, advertiser, and the paying entity. Ads covered by EU disclosure rules also carry run dates, target countries and impression bands; ads outside those rules do not, and those fields come back null rather than guessed.

ParameterTypeRequiredDescription
urlstringyesAd Library URL (linkedin.com/ad-library/detail/...) or the numeric ad id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/linkedin/ad?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/linkedin/ad?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/linkedin/ad",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/linkedin/ads/search1 creditcacheablebatchable

Search ads

Search LinkedIn's public Ad Library by advertiser or keyword. Pass company (a company page slug or numeric id) to list one advertiser's ads, keyword to search copy, or both. Returns the first page LinkedIn server-renders — about 25 ads; the total number of matches is in raw.totalMatches. **Required:** Pass company, keyword, or both — the Ad Library will not return an unfiltered archive.

ParameterTypeRequiredDescription
companystringnoCompany page slug ("microsoft") or numeric company id ("1035")
keywordstringnoWords to match in the ad copy
countriesstringnoComma-separated ISO-3166 country codes the ad reached, e.g. "US,GB"
start_datestringnoEarliest run date, YYYY-MM-DD
end_datestringnoLatest run date, YYYY-MM-DD

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/linkedin/ads/search?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/linkedin/ads/search?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/linkedin/ads/search",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/linkedin/company1 creditcacheablebatchableneeds proxies

Company page

A LinkedIn company page: description, follower count, headquarters, employee count and logo. Also works for school and showcase pages.

ParameterTypeRequiredDescription
urlstringyesCompany URL (linkedin.com/company/...) or the company slug

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/linkedin/company?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/linkedin/company?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/linkedin/company",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/linkedin/company/posts1 creditcacheablebatchableneeds proxies

Company posts

Recent posts from a company page, with reaction and comment counts. Read from the company page itself: LinkedIn's dedicated /posts/ tab is behind the sign-in wall, but the same updates render on the public page. That caps the result at roughly the last ten posts — there is no logged-out pagination, so hasMore is always false. publishedAt is an absolute timestamp for the posts LinkedIn describes in structured data and a relative age ("3w") for the rest; raw.withAbsoluteDates says how many got the former. Use linkedin.post on any id for an exact time.

ParameterTypeRequiredDescription
urlstringyesCompany URL (linkedin.com/company/...) or the company slug

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/linkedin/company/posts?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/linkedin/company/posts?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/linkedin/company/posts",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/linkedin/post1 creditcacheablebatchableneeds proxies

Post details

One LinkedIn post: full text, media, author, publication time, reactions and comment count. Top-level comments LinkedIn publishes on the page ride along in raw.comments.

ParameterTypeRequiredDescription
urlstringyesPost URL (linkedin.com/posts/... or /feed/update/urn:li:activity:...) or the numeric id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/linkedin/post?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/linkedin/post?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/linkedin/post",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/linkedin/post/transcript1 creditcacheablebatchableneeds proxiesexperimental

Post transcript

Captions for a LinkedIn video post, as one text block plus timed cues. Only returns data where the poster attached a caption track AND LinkedIn exposes it to logged-out viewers — probed 2026-08-20, native video posts ship mp4 sources and a poster frame with no caption track, so expect this to come back empty for most posts. Empty results are never charged.

ParameterTypeRequiredDescription
urlstringyesPost URL or the numeric activity id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/linkedin/post/transcript?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/linkedin/post/transcript?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/linkedin/post/transcript",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/linkedin/profile1 creditcacheablebatchableneeds proxies

Person's profile

A LinkedIn member's public profile: name, headline, location, follower count, avatar, current employers and education. LinkedIn masks parts of a logged-out profile with asterisks; masked values are dropped rather than returned as ****.

ParameterTypeRequiredDescription
urlstringyesProfile URL (linkedin.com/in/...) or the profile slug

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/linkedin/profile?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/linkedin/profile?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/linkedin/profile",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/linkedin/search/posts1 creditcacheableneeds proxiesexperimental

Search posts

Keyword search over LinkedIn posts. LinkedIn gates content search behind sign-in for every logged-out caller — verified 2026-08-20, /search/results/content/ redirects to /uas/login regardless of origin IP — and we do not scrape authenticated sessions, so this endpoint reports the gate rather than pretending to be broken. It is shipped so callers get one clear, unbilled answer instead of a 404 on a documented route.

ParameterTypeRequiredDescription
querystringyesSearch terms
date_postedpast-24h | past-week | past-monthnoRestrict to recent posts
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/linkedin/search/posts?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/linkedin/search/posts?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/linkedin/search/posts",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Linkme

GET/v1/linkme1 creditcacheablebatchableneeds proxies

LinkMe page

Public LinkMe page as a creator profile: display name, bio, avatar, and every outbound link in order.

ParameterTypeRequiredDescription
urlstringyesPage URL (https://linkme.bio/<username>) or just the username

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/linkme?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/linkme?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/linkme",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Linktree

GET/v1/linktree1 creditcacheablebatchable

Linktree page

Public Linktree page as a creator profile: display name, bio, avatar, and every outbound link in order.

ParameterTypeRequiredDescription
urlstringyesPage URL (https://linktr.ee/<username>) or just the username

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/linktree?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/linktree?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/linktree",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Pillar

GET/v1/pillar1 creditcacheablebatchableneeds proxies

Pillar page

Public Pillar page as a creator profile: display name, bio, avatar, and every outbound link in order.

ParameterTypeRequiredDescription
urlstringyesPage URL (https://pillar.io/<username>) or just the username

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/pillar?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/pillar?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/pillar",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Pinterest

GET/v1/pinterest/board1 creditcacheablebatchable

Board and its pins

Board metadata plus a page of its pins. Pass the cursor from the previous response to page through the board.

ParameterTypeRequiredDescription
urlstringyesBoard URL, e.g. https://www.pinterest.com/pinterest/spice-up-your-dinner-plans/
cursorstringnoBookmark from the previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/pinterest/board?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/pinterest/board?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/pinterest/board",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/pinterest/pin1 creditcacheablebatchable

Pin details

Public details for a pin: title, description, destination link, saves, reactions and full-resolution media. Saves map to shareCount.

ParameterTypeRequiredDescription
urlstringyesPin URL, e.g. https://www.pinterest.com/pin/1130122100248990600/

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/pinterest/pin?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/pinterest/pin?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/pinterest/pin",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/pinterest/user/boards1 creditcacheablebatchable

Boards owned by a user

Public boards on a profile, most recently pinned-to first, with pin and follower counts.

ParameterTypeRequiredDescription
handlestringyesUsername, e.g. "pinterest"
cursorstringnoBookmark from the previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/pinterest/user/boards?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/pinterest/user/boards?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/pinterest/user/boards",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Reddit

GET/v1/reddit/post1 creditcacheablebatchableneeds proxies

Post details

One Reddit post with its score, comment count, body text and media. Use reddit.postComments for the comment tree — they are separate endpoints so a post with no comments is still a paid, cached result rather than an empty one.

ParameterTypeRequiredDescription
urlstringyesPost URL (reddit.com/r/.../comments/...) or a post id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/reddit/post?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/reddit/post?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/reddit/post",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/reddit/post/comment/replies1 creditcacheablebatchableneeds proxies

Comment replies

The reply thread under a single comment — the continuation behind Reddit's "load more comments". Takes a comment permalink, or "postId:commentId".

ParameterTypeRequiredDescription
urlstringyesComment permalink (.../comments/{post}/{slug}/{comment}/) or "postId:commentId"
depthnumbernoReply levels below the comment, 1-10. Default 6.
sortconfidence | top | new | controversial | old | qanodefaults to confidence

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/reddit/post/comment/replies?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/reddit/post/comment/replies?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/reddit/post/comment/replies",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/reddit/post/comments1 creditcacheablebatchableneeds proxies

Post comments

A post's comment tree, flattened into reading order with parentId preserved so callers can rebuild it. Reddit collapses deep threads behind continuation stubs; fetch those with reddit.commentReplies.

ParameterTypeRequiredDescription
urlstringyesPost URL (reddit.com/r/.../comments/...) or a post id
sortconfidence | top | new | controversial | old | qanoReddit's comment sorts. "confidence" is the site default ("Best").defaults to confidence
depthnumbernoReply levels to walk, 1-10. Default 4.
limitnumbernoTop-level comments to request, 1-500. Default 100.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/reddit/post/comments?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/reddit/post/comments?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/reddit/post/comments",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/reddit/subreddit1 creditcacheablebatchableneeds proxies

Subreddit posts

Posts from a subreddit, sorted the way Reddit sorts them. sort=top and sort=controversial accept a timeframe. Falls back to Reddit's Atom feed when the JSON surface is blocked — raw.via says which answered, and the Atom path returns no scores or comment counts.

ParameterTypeRequiredDescription
subredditstringyesSubreddit name ("aww", "r/aww") or a full reddit.com/r/... URL
sorthot | new | top | rising | controversialnodefaults to hot
timeframehour | day | week | month | year | allnoWindow for sort=top / sort=controversial. Default "day".
limitnumbernoPosts per page, 1-100. Default 25.
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/reddit/subreddit?subreddit=%3Csubreddit%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  subreddit: '<subreddit>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/reddit/subreddit?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/reddit/subreddit",
    params={
        "subreddit": "<subreddit>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/reddit/subreddit/details1 creditcacheablebatchableneeds proxies

Subreddit details

Public metadata for a subreddit: subscribers, people online now, description, icons, creation date, and whether it is private or restricted.

ParameterTypeRequiredDescription
subredditstringyesSubreddit name ("aww", "r/aww") or a full reddit.com/r/... URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/reddit/subreddit/details?subreddit=%3Csubreddit%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  subreddit: '<subreddit>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/reddit/subreddit/details?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/reddit/subreddit/details",
    params={
        "subreddit": "<subreddit>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/reddit/user1 creditcacheablebatchableneeds proxies

User profile

A Reddit account's public profile: display name, description, avatar, account age, and karma (returned under raw.karma, since the unified schema has no karma field).

ParameterTypeRequiredDescription
usernamestringyesUsername ("spez", "u/spez") or a reddit.com/user/... URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/reddit/user?username=%3Cusername%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  username: '<username>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/reddit/user?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/reddit/user",
    params={
        "username": "<username>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/reddit/user/posts1 creditcacheablebatchableneeds proxies

User posts

Posts submitted by a Reddit account, newest first by default. Falls back to the account's Atom feed when the JSON surface is blocked.

ParameterTypeRequiredDescription
usernamestringyesUsername ("spez", "u/spez") or a reddit.com/user/... URL
sortnew | hot | topnodefaults to new
timeframehour | day | week | month | year | allnoWindow for sort=top. Default "all".
limitnumbernoPosts per page, 1-100. Default 25.
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/reddit/user/posts?username=%3Cusername%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  username: '<username>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/reddit/user/posts?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/reddit/user/posts",
    params={
        "username": "<username>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Rumble

GET/v1/rumble/channel/videos1 creditcacheablebatchableneeds proxies

Channel videos

A Rumble channel's public uploads, newest first, 25 per page. Pass the cursor from the previous response to page.

ParameterTypeRequiredDescription
handlestringyesChannel handle (Asmongold), c/Handle, user/Handle, or a full rumble.com URL
cursorstringnopagination.cursor from the previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/rumble/channel/videos?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/rumble/channel/videos?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/rumble/channel/videos",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/rumble/video1 creditcacheablebatchableneeds proxies

Video details

Public metadata for a Rumble video: exact view count, likes and dislikes, comment count, duration, upload date, channel and follower count.

ParameterTypeRequiredDescription
urlstringyesRumble watch URL (rumble.com/v7e9i52-slug.html) or a bare permalink id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/rumble/video?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/rumble/video?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/rumble/video",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/rumble/video/comments1 creditcacheablebatchableneeds proxies

Video comments

Public comments on a Rumble video, including replies. Rumble hides comments behind a login on some videos; when it does, this returns an unbilled empty result rather than logging in.

ParameterTypeRequiredDescription
urlstringyesRumble watch URL (rumble.com/v7e9i52-slug.html) or a bare permalink id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/rumble/video/comments?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/rumble/video/comments?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/rumble/video/comments",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/rumble/video/transcript1 creditcacheablebatchableneeds proxies

Video transcript

A Rumble video's captions as one text block plus timed cues. Returns the requested language when the video has it, otherwise the default track.

ParameterTypeRequiredDescription
urlstringyesRumble watch URL (rumble.com/v7e9i52-slug.html) or a bare permalink id
languagestringnoLanguage code, e.g. "en"

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/rumble/video/transcript?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/rumble/video/transcript?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/rumble/video/transcript",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Snapchat

GET/v1/snapchat/profile1 creditcacheablebatchable

User profile

Public Snapchat profile. Creator and business accounts return subscriber count, bio, website and avatar; personal accounts return only the handle and display name, which is all Snapchat publishes for them.

ParameterTypeRequiredDescription
handlestringyesHandle (teamsnapchat) or a snapchat.com/add/<handle> URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/snapchat/profile?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/snapchat/profile?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/snapchat/profile",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/snapchat/spotlight1 creditcacheablebatchable

Spotlight by link

A public Snapchat Spotlight video: view count, duration, creator, thumbnail, media URL, and the auto-generated transcript when Snapchat has one.

ParameterTypeRequiredDescription
urlstringyesSpotlight URL (https://www.snapchat.com/spotlight/<id>)

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/snapchat/spotlight?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/snapchat/spotlight?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/snapchat/spotlight",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/snapchat/spotlight/comments1 creditcacheablebatchable

Spotlight comments by link

Public comments on a Snapchat Spotlight, ranked the way Snapchat ranks them, with reaction and threaded-reply counts.

ParameterTypeRequiredDescription
urlstringyesSpotlight URL (https://www.snapchat.com/spotlight/<id>)

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/snapchat/spotlight/comments?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/snapchat/spotlight/comments?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/snapchat/spotlight/comments",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Soundcloud

GET/v1/soundcloud/artist1 creditcacheablebatchable

Artist profile

Public SoundCloud profile: followers, following, track count, bio, avatar and header image.

ParameterTypeRequiredDescription
handlestringyesHandle (flume), or a full soundcloud.com profile URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/soundcloud/artist?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/soundcloud/artist?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/soundcloud/artist",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/soundcloud/artist/tracks1 creditcacheablebatchable

Artist tracks

An artist's public uploads, newest first. Pass the cursor from the previous response to page.

ParameterTypeRequiredDescription
handlestringyesHandle (flume), or a full soundcloud.com profile URL
limitnumbernodefaults to 50
cursorstringnopagination.cursor from the previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/soundcloud/artist/tracks?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/soundcloud/artist/tracks?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/soundcloud/artist/tracks",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/soundcloud/track1 creditcacheablebatchable

Track details

Public metadata for a SoundCloud track: plays, likes, reposts, comments, duration, genre and publisher metadata (ISRC, label, writers).

ParameterTypeRequiredDescription
urlstringyesTrack URL, or "user/track-slug"

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/soundcloud/track?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/soundcloud/track?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/soundcloud/track",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Spotify

GET/v1/spotify/album1 creditcacheablebatchable

Album details

Public Spotify album: title, artist, artwork and total runtime. The full track listing is in raw — add include_raw=true.

ParameterTypeRequiredDescription
idstringyesSpotify album id, spotify:album: URI, or open.spotify.com album URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/spotify/album?id=%3Cid%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  id: '<id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/spotify/album?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/spotify/album",
    params={
        "id": "<id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/spotify/artist1 creditcacheablebatchable

Artist details

Public Spotify artist: name, artwork and current top tracks (in raw). Follower counts are not in Spotify's public embed payload and are returned as null unless SPOTIFY_CLIENT_ID/SECRET are configured — see /v1/spotify/search, which reads the official API.

ParameterTypeRequiredDescription
idstringyesSpotify artist id, spotify:artist: URI, or open.spotify.com artist URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/spotify/artist?id=%3Cid%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  id: '<id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/spotify/artist?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/spotify/artist",
    params={
        "id": "<id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/spotify/podcast1 creditcacheablebatchable

Podcast details

A Spotify podcast: title, publisher, description, artwork and episode count. Uses Spotify's official Web API — the public embed for a show resolves to that show's latest EPISODE, not to the show itself, so there is no keyless route to this data.

ParameterTypeRequiredDescription
idstringyesSpotify show id, spotify:show: URI, or open.spotify.com show URL
marketstringnoISO 3166-1 alpha-2 market codedefaults to US

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/spotify/podcast?id=%3Cid%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  id: '<id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/spotify/podcast?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/spotify/podcast",
    params={
        "id": "<id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/spotify/podcast/episodes1 creditcacheablebatchable

Podcast episodes

Episodes for a Spotify podcast, newest first. Pass the cursor from the previous response to page.

ParameterTypeRequiredDescription
idstringyesSpotify show id, spotify:show: URI, or open.spotify.com show URL
limitnumbernodefaults to 50
cursorstringnopagination.cursor from the previous response
marketstringnoISO 3166-1 alpha-2 market codedefaults to US

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/spotify/podcast/episodes?id=%3Cid%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  id: '<id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/spotify/podcast/episodes?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/spotify/podcast/episodes",
    params={
        "id": "<id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/spotify/track1 creditcacheablebatchable

Track details

Public Spotify track: title, artists, artwork, duration, release date, explicit flag, and the preview clip URL.

ParameterTypeRequiredDescription
idstringyesSpotify track id, spotify:track: URI, or open.spotify.com track URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/spotify/track?id=%3Cid%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  id: '<id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/spotify/track?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/spotify/track",
    params={
        "id": "<id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Threads

GET/v1/threads/post1 creditcacheablebatchable

Post

A single public Threads post with like count, reply count, and any attached media.

ParameterTypeRequiredDescription
urlstringyesPost URL (https://www.threads.com/@handle/post/ABC) or a shortcode

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/threads/post?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/threads/post?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/threads/post",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/threads/profile1 creditcacheablebatchable

Profile

Public Threads profile: follower count, bio, bio links, avatar, and verification status.

ParameterTypeRequiredDescription
handlestringyesHandle (@zuck) or a threads.com profile URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/threads/profile?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/threads/profile?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/threads/profile",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/threads/search/users1 creditcacheablebatchableneeds proxies

Search users

Public Threads accounts matching a keyword.

ParameterTypeRequiredDescription
querystringyesKeyword or partial handle

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/threads/search/users?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/threads/search/users?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/threads/search/users",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/threads/user/posts1 creditcacheablebatchable

User posts

Recent public posts from a Threads profile, with like and reply counts.

ParameterTypeRequiredDescription
handlestringyesHandle (@zuck) or a threads.com profile URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/threads/user/posts?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/threads/user/posts?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/threads/user/posts",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

TikTok

GET/v1/tiktok/collection/videos1 creditcacheablebatchableneeds proxiesexperimental

Collection videos

Videos in a public TikTok collection — a creator-curated playlist of other people's posts as well as their own. Requires a configured TikTok signer. **Required:** Pass either url or collection_id.

ParameterTypeRequiredDescription
urlstringnoCollection URL, e.g. https://www.tiktok.com/@nasa/collection/Artemis-7123…
collection_idstringnoNumeric collection id
countnumbernoItems per page (default 20, max 30)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/collection/videos?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/collection/videos?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/collection/videos",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/comment-replies1 creditcacheablebatchableneeds proxiesexperimental

Replies to a comment

The reply thread under one TikTok comment. parentId on each reply points back at the comment it answers, so nested threads reconstruct cleanly. Requires a configured TikTok signer.

ParameterTypeRequiredDescription
comment_idstringyesid of the parent comment, from tiktok.comments
urlstringyesThe video the comment is on — URL, share link, or numeric id
countnumbernoItems per page (default 20, max 50)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/comment-replies?comment_id=%3Ccomment_id%3E&url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  comment_id: '<comment_id>',
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/comment-replies?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/comment-replies",
    params={
        "comment_id": "<comment_id>",
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/comments1 creditcacheablebatchableneeds proxiesexperimental

Comments on a video

Top-level comments on a TikTok, with like counts, reply counts, pinned status and a flag for the creator's own replies. Use tiktok.commentReplies to expand a thread. Requires a configured TikTok signer.

ParameterTypeRequiredDescription
urlstringyesVideo URL (preferred), share link, or numeric video id
countnumbernoItems per page (default 20, max 50)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/comments?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/comments?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/comments",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/creators/popular1 creditcacheablebatchableneeds proxiesexperimental

Popular creators

Creators trending in a market, from TikTok's own Creative Center leaderboard. Filter by country, follower band and category.

ParameterTypeRequiredDescription
regionstringnoTwo-letter market code (US, GB, ID…). TikTok feeds and catalogues are per-market.
period7 | 30 | 120noTrailing window in days: 7, 30 or 120defaults to 7
follower_band1k-10k | 10k-100k | 100k-1m | 1m+noRestrict to creators in this follower range
countnumbernoItems per page (default 20, max 50)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/creators/popular?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/creators/popular?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/creators/popular",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/followers1 creditcacheablebatchableneeds proxiesexperimental

Accounts following a creator

The public follower list for a TikTok account, newest first. TikTok caps how deep this list can be walked regardless of paging. Requires a configured TikTok signer.

ParameterTypeRequiredDescription
handlestringyesHandle (@nike), or a full tiktok.com profile URL
countnumbernoItems per page (default 30, max 50)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/followers?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/followers?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/followers",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/following1 creditcacheablebatchableneeds proxiesexperimental

Accounts a creator follows

The accounts a TikTok creator follows, newest first. Hidden entirely when the creator has set their following list to private. Requires a configured TikTok signer.

ParameterTypeRequiredDescription
handlestringyesHandle (@nike), or a full tiktok.com profile URL
countnumbernoItems per page (default 30, max 50)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/following?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/following?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/following",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/hashtag1 creditcacheablebatchableneeds proxiesexperimental

Hashtag details

Stats for a TikTok hashtag: total videos and total views, plus its description and cover. Read straight off the tag page, so it needs no signer.

ParameterTypeRequiredDescription
hashtagstringyesTag without the # (fyp), or a full /tag/ URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/hashtag?hashtag=%3Chashtag%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  hashtag: '<hashtag>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/hashtag?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/hashtag",
    params={
        "hashtag": "<hashtag>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/hashtag-videos1 creditcacheablebatchableneeds proxiesexperimental

Videos using a hashtag

TikToks carrying a given hashtag, in TikTok's own feed order. Resolves the tag to its numeric id from the tag page, then pages the feed — which needs a configured TikTok signer.

ParameterTypeRequiredDescription
hashtagstringyesTag without the # (fyp), or a full /tag/ URL
countnumbernoItems per page (default 30, max 30)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/hashtag-videos?hashtag=%3Chashtag%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  hashtag: '<hashtag>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/hashtag-videos?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/hashtag-videos",
    params={
        "hashtag": "<hashtag>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/live1 creditcacheablebatchableneeds proxiesexperimental

Live stream info

Details of a creator's stream while they are live: room id, title, cover, current viewers and start time. A creator who is not live returns empty_result, which is a real answer and costs nothing — that makes this usable as a cheap "are they live?" poll.

ParameterTypeRequiredDescription
handlestringyesHandle (@nike), or a full tiktok.com profile URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/live?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/live?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/live",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/playlist-videos1 creditcacheablebatchableneeds proxiesexperimental

Videos in a playlist

The videos inside one TikTok playlist, in the creator's chosen order. Requires a configured TikTok signer.

ParameterTypeRequiredDescription
playlist_idstringyesid from tiktok.playlists, or a /playlist/ URL
countnumbernoItems per page (default 30, max 30)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/playlist-videos?playlist_id=%3Cplaylist_id%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  playlist_id: '<playlist_id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/playlist-videos?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/playlist-videos",
    params={
        "playlist_id": "<playlist_id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/playlists1 creditcacheablebatchableneeds proxiesexperimental

A creator's playlists

The playlists (TikTok calls them "mixes") a creator has organised their videos into. Pair with tiktok.playlistVideos to walk one. Requires a configured TikTok signer.

ParameterTypeRequiredDescription
handlestringyesHandle (@nike), or a full tiktok.com profile URL
countnumbernoItems per page (default 20, max 30)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/playlists?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/playlists?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/playlists",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/product1 creditcacheablebatchableneeds proxiesexperimental

Product details

A single TikTok Shop product: title, price, images, rating, review and sales counts, and the seller. Read from the server-rendered product page, so it needs no signer.

ParameterTypeRequiredDescription
urlstringyesProduct id, or a tiktok.com/view/product/… URL
regionstringnoTwo-letter market code (US, GB, ID…). TikTok feeds and catalogues are per-market.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/product?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/product?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/product",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/profile1 creditcacheablebatchableneeds proxiesexperimental

Profile details

Public profile for a TikTok account: followers, following, video count, bio, bio link, verification and account region. Private accounts return their public shell with isPrivate: true rather than an error — that is a real answer, not a failure. Total likes received (TikTok's "hearts") is in raw, since it is a like total rather than the lifetime view count viewCount means elsewhere in the schema.

ParameterTypeRequiredDescription
handlestringyesHandle (@nike), or a full tiktok.com profile URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/profile?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/profile?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/profile",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/profile/region1 creditcacheablebatchableneeds proxiesexperimental

Creator region

The market TikTok assigns a creator's account. Read from TikTok's own region field — on the profile where TikTok publishes one, otherwise from the region stamped on the creator's recent posts. Never inferred from language, timezone or content. **Required:** Pass either handle or url.

ParameterTypeRequiredDescription
handlestringnoCreator handle, e.g. @nasa
urlstringnoProfile URL, e.g. https://www.tiktok.com/@nasa

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/profile/region?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/profile/region?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/profile/region",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/search/keyword1 creditcacheablebatchableneeds proxiesexperimental

Search videos by keyword

TikToks matching a search term, with the same normalised engagement fields as every other post endpoint. sort_by and date_posted map onto TikTok's own search filters. Requires a configured TikTok signer.

ParameterTypeRequiredDescription
querystringyesSearch term
sort_byrelevance | most_likednoTikTok's own two search orderingsdefaults to relevance
date_postedall | yesterday | week | month | three_months | six_monthsnoRestrict to videos posted within this windowdefaults to all
countnumbernoItems per page (default 12, max 30)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/search/keyword?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/search/keyword?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/search/keyword",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/search/suggestions1 creditcacheablebatchableneeds proxiesexperimental

Search suggestions

TikTok's typeahead completions for a partial query — what the platform thinks people are looking for. Useful for keyword research.

ParameterTypeRequiredDescription
querystringyesPartial search term

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/search/suggestions?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/search/suggestions?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/search/suggestions",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/search/top1 creditcacheablebatchableneeds proxiesexperimental

Top (blended) search

TikTok's blended "Top" search tab: the highest-ranked videos AND accounts for a query, returned as two typed lists. Requires a configured TikTok signer.

ParameterTypeRequiredDescription
querystringyesSearch terms
countnumbernoItems per page (default 12, max 30)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/search/top?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/search/top?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/search/top",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/search/users1 creditcacheablebatchableneeds proxiesexperimental

Search creators

TikTok accounts matching a query, with follower counts and verification. Requires a configured TikTok signer.

ParameterTypeRequiredDescription
querystringyesSearch term
countnumbernoItems per page (default 12, max 30)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/search/users?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/search/users?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/search/users",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/shop/product/reviews1 creditcacheablebatchableneeds proxiesexperimental

Product reviews

Public reviews on a TikTok Shop product, with star rating, reviewer, photos and the purchased variant. Requires a configured TikTok signer.

ParameterTypeRequiredDescription
urlstringyesProduct id, or a tiktok.com/view/product/… URL
countnumbernoItems per page (default 20, max 50)
cursorstringnopagination.cursor from a previous response
regionstringnoTwo-letter market code (US, GB, ID…). TikTok feeds and catalogues are per-market.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/shop/product/reviews?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/shop/product/reviews?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/shop/product/reviews",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/shop/products1 creditcacheablebatchableneeds proxiesexperimental

Seller's product catalogue

Products listed by a TikTok Shop seller. Pass the seller's handle or a shop URL. Requires a configured TikTok signer.

ParameterTypeRequiredDescription
urlstringyesSeller handle (@shopname) or a TikTok shop URL
countnumbernoItems per page (default 20, max 50)
cursorstringnopagination.cursor from a previous response
regionstringnoTwo-letter market code (US, GB, ID…). TikTok feeds and catalogues are per-market.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/shop/products?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/shop/products?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/shop/products",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/shop/search1 creditcacheablebatchableneeds proxiesexperimental

Search TikTok Shop

Product search across TikTok Shop. Requires a configured TikTok signer.

ParameterTypeRequiredDescription
querystringyesSearch terms
countnumbernoItems per page (default 20, max 50)
cursorstringnopagination.cursor from a previous response
regionstringnoTwo-letter market code (US, GB, ID…). TikTok feeds and catalogues are per-market.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/shop/search?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/shop/search?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/shop/search",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/song1 creditcacheablebatchableneeds proxiesexperimental

Sound / song details

Details for a TikTok sound: title, artist, album, cover, clip length, and how many videos use it. Read from the music page, so it needs no signer.

ParameterTypeRequiredDescription
songstringyesMusic id, or a full tiktok.com/music/… URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/song?song=%3Csong%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  song: '<song>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/song?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/song",
    params={
        "song": "<song>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/song-videos1 creditcacheablebatchableneeds proxiesexperimental

Videos using a sound

TikToks built on a given sound — the endpoint behind "who is using my track". Requires a configured TikTok signer.

ParameterTypeRequiredDescription
songstringyesMusic id, or a full tiktok.com/music/… URL
countnumbernoItems per page (default 30, max 30)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/song-videos?song=%3Csong%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  song: '<song>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/song-videos?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/song-videos",
    params={
        "song": "<song>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/songs/popular1 creditcacheablebatchableneeds proxiesexperimental

Popular songs

Sounds trending in a market — the endpoint behind music A&R and sync-licensing research. From TikTok's Creative Center.

ParameterTypeRequiredDescription
regionstringnoTwo-letter market code (US, GB, ID…). TikTok feeds and catalogues are per-market.
period7 | 30 | 120noTrailing window in days: 7, 30 or 120defaults to 7
countnumbernoItems per page (default 20, max 50)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/songs/popular?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/songs/popular?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/songs/popular",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/transcript1 creditcacheablebatchableneeds proxiesexperimental

Video transcript

The spoken transcript of a TikTok, as one text block plus timed cues. Returns the ORIGINAL spoken-language track by default rather than whichever track TikTok lists first, so the text reflects what was actually said. Pass language for a specific track — a miss is an error listing what is available, never a silent substitution into another language.

ParameterTypeRequiredDescription
urlstringyesVideo URL (preferred), share link, or numeric video id
languagestringnoBCP-47 or ISO-639 code, e.g. "en", "es", "pt-BR". Omit for the original spoken track.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/transcript?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/transcript?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/transcript",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/user-videos1 creditcacheablebatchableneeds proxiesexperimental

Videos posted by a creator

A creator's public posts, newest first, with view/like/comment/share counts. Photo posts are included and typed as image or carousel. Paging past the first response requires a configured TikTok signer; without one the first page still returns from the profile page itself, and raw.via says which path answered.

ParameterTypeRequiredDescription
handlestringyesHandle (@nike), or a full tiktok.com profile URL
countnumbernoItems per page (default 35, max 35)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/user-videos?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/user-videos?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/user-videos",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/user/showcase1 creditcacheablebatchableneeds proxiesexperimental

Creator's product showcase

Products a creator has pinned to their profile showcase — what they are actually promoting, as opposed to what they sell. Requires a configured TikTok signer.

ParameterTypeRequiredDescription
handlestringyesCreator handle, e.g. @charlidamelio
countnumbernoItems per page (default 20, max 50)
cursorstringnopagination.cursor from a previous response
regionstringnoTwo-letter market code (US, GB, ID…). TikTok feeds and catalogues are per-market.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/user/showcase?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/user/showcase?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/user/showcase",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/video1 creditcacheablebatchableneeds proxiesexperimental

Video or photo-post details

Full public metadata for one TikTok: caption, hashtags, mentions, author, sound, duration, and view/like/comment/share counts. Photo posts return every image in mediaUrls. Accepts a full URL, a share link (vm.tiktok.com), or a numeric video id.

ParameterTypeRequiredDescription
urlstringyesVideo URL (preferred), share link, or numeric video id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/video?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/video?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/video",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/tiktok/videos/popular1 creditcacheablebatchableneeds proxiesexperimental

Popular videos

Videos trending in a market over a trailing window, from TikTok's Creative Center. Distinct from /v1/tiktok/trending, which is the personalised For You feed.

ParameterTypeRequiredDescription
regionstringnoTwo-letter market code (US, GB, ID…). TikTok feeds and catalogues are per-market.
period7 | 30 | 120noTrailing window in days: 7, 30 or 120defaults to 7
countnumbernoItems per page (default 20, max 50)
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/tiktok/videos/popular?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/tiktok/videos/popular?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/tiktok/videos/popular",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Truthsocial

GET/v1/truthsocial/post1 creditcacheablebatchableneeds proxies

Post

A single public Truth with its engagement counts and attached media.

ParameterTypeRequiredDescription
urlstringyesPost URL (https://truthsocial.com/@handle/posts/<id>) or a bare numeric post id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/truthsocial/post?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/truthsocial/post?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/truthsocial/post",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/truthsocial/profile1 creditcacheablebatchableneeds proxies

Profile

Public Truth Social profile: follower and following counts, Truth count, bio, avatar, header image, and verification status.

ParameterTypeRequiredDescription
handlestringyesHandle (@realDonaldTrump) or a truthsocial.com profile URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/truthsocial/profile?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/truthsocial/profile?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/truthsocial/profile",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/truthsocial/user/posts1 creditcacheablebatchableneeds proxies

User posts

Recent public Truths from an account, newest first, with favourite, reply and ReTruth counts.

ParameterTypeRequiredDescription
handlestringyesHandle or profile URL
user_idstringnoNumeric account id, if you already have it
countnumbernodefaults to 20
cursorstringnopagination.cursor from a previous response (Mastodon max_id)
exclude_repliesbooleanno—

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/truthsocial/user/posts?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/truthsocial/user/posts?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/truthsocial/user/posts",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

Twitch

GET/v1/twitch/clip1 creditcacheablebatchable

Clip details

Public metadata for a Twitch clip: views, duration, creator, broadcaster, category, and the offset into the source VOD.

ParameterTypeRequiredDescription
urlstringyesClip URL (twitch.tv/<channel>/clip/<slug> or clips.twitch.tv/<slug>) or a bare slug

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/twitch/clip?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/twitch/clip?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/twitch/clip",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/twitch/profile1 creditcacheablebatchable

Channel profile

Public Twitch channel: followers, partner/affiliate status, bio, avatar, banner, account age, and whether the channel is live right now.

ParameterTypeRequiredDescription
handlestringyesChannel login (shroud), or a twitch.tv URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/twitch/profile?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/twitch/profile?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/twitch/profile",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/twitch/user/schedule1 creditcacheablebatchable

Stream schedule

A channel's published schedule for the current week, plus the next upcoming segment. Segments are returned as posts of type live whose publishedAt is the scheduled start time.

ParameterTypeRequiredDescription
handlestringyesChannel login (hasanabi), or a twitch.tv URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/twitch/user/schedule?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/twitch/user/schedule?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/twitch/user/schedule",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/twitch/user/videos1 creditcacheablebatchable

Channel videos

A channel's public VODs, highlights or uploads. Returns up to 100 per call — Twitch gates deeper pages behind a browser integrity challenge, and we do not run browser sessions.

ParameterTypeRequiredDescription
handlestringyesChannel login (shroud), or a twitch.tv URL
filter_byarchive | highlight | uploadnoarchive = past broadcasts, highlight = clipped highlights, upload = uploaded videosdefaults to archive
sort_bytime | viewsnodefaults to time
limitnumbernodefaults to 30

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/twitch/user/videos?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/twitch/user/videos?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/twitch/user/videos",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

X / Twitter

GET/v1/twitter/community1 creditcacheablebatchableneeds proxies

Community details

Public details for an X Community: name, description, member count, topic, join policy, banner and the creator's handle. Read from the server-rendered community page, which X still serves to logged-out callers.

ParameterTypeRequiredDescription
urlstringyesCommunity URL (x.com/i/communities/...) or the numeric id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/twitter/community?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/twitter/community?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/twitter/community",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/twitter/community/tweets1 creditcacheablebatchableneeds proxies

Community posts

Recent posts in an X Community, with likes, retweets, replies and **view counts** — the community page publishes metrics X's embed CDN does not. One page only: X serves logged-out callers a single rendered batch and no continuation token, so hasMore is always false.

ParameterTypeRequiredDescription
urlstringyesCommunity URL (x.com/i/communities/...) or the numeric id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/twitter/community/tweets?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/twitter/community/tweets?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/twitter/community/tweets",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/twitter/profile1 creditcacheablebatchableneeds proxies

Profile details

Public profile for an X account. With TWITTER_BEARER_TOKEN set this is the full profile — bio, location, follower/following/post counts, join date. Without one, X exposes only handle, id, display name, avatar and verified status to logged-out callers, and the call is refunded to 0 credits because that is not worth charging for.

ParameterTypeRequiredDescription
handlestringyesHandle (@jack), or a full x.com profile URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/twitter/profile?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/twitter/profile?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/twitter/profile",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/twitter/tweet1 creditcacheablebatchable

Post details

One public post with its text, media and engagement. Served from X's embed CDN, which is the most durable logged-out surface X still operates; with TWITTER_BEARER_TOKEN set it uses the official API instead and adds retweet, quote and impression counts.

ParameterTypeRequiredDescription
urlstringyesPost URL (x.com/user/status/123...) or a bare post id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/twitter/tweet?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/twitter/tweet?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/twitter/tweet",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/twitter/tweet/transcript1 creditcacheablebatchableexperimental

Post transcript

Captions for a video post on X, as one text block plus timed cues. Sourced from the caption track in the video's HLS playlist, which is the only transcript X exposes to logged-out callers — posts whose author never attached captions return an empty result and are not charged.

ParameterTypeRequiredDescription
urlstringyesPost URL (x.com/user/status/123...) or a bare post id
languagestringnoBCP-47 code, e.g. "en". Defaults to the first track.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/twitter/tweet/transcript?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/twitter/tweet/transcript?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/twitter/tweet/transcript",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/twitter/user-tweets1 creditcacheablebatchableneeds proxies

Recent posts from an account

An account's recent public posts. With TWITTER_BEARER_TOKEN this pages through the timeline with real engagement metrics; without one it returns the single page X's embedded timeline exposes (roughly 20 posts, likes and replies only).

ParameterTypeRequiredDescription
handlestringyesHandle (@jack), or a full x.com profile URL
countnumbernoPosts per page, 5-100. Default 20. Official API only.
cursorstringnopagination.cursor from a previous response. Official API only.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/twitter/user-tweets?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/twitter/user-tweets?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/twitter/user-tweets",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

YouTube

GET/v1/youtube/channel1 creditcacheablebatchable

Channel details

Public details for a YouTube channel: subscribers, video count, description, links.

ParameterTypeRequiredDescription
handlestringyesHandle (@mrbeast), channel id (UC...), or full URL

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/channel?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/channel?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/channel",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/channel-videos1 creditcacheablebatchable

Channel videos

Recent public uploads for a channel. Use tab to switch between videos and shorts.

ParameterTypeRequiredDescription
handlestringyesHandle (@mrbeast), channel id, or full URL
tabvideos | shorts | streamsnodefaults to videos

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/channel-videos?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/channel-videos?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/channel-videos",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/channel/community-posts1 creditcacheablebatchable

Channel community posts

A channel's Posts tab (what YouTube used to call Community). Images, multi-image carousels, shared videos and polls all come back as posts; poll options are under raw.

ParameterTypeRequiredDescription
handlestringyesHandle (@mrbeast), channel id (UC…), or full URL
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/channel/community-posts?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/channel/community-posts?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/channel/community-posts",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/channel/lives1 creditcacheablebatchable

Channel live streams

A channel's Live tab: streams that are live now, scheduled, or finished and still on the tab. viewCount is concurrent viewers while a stream is live and total views once it ends — YouTube swaps the label, and we surface whichever it gave us.

ParameterTypeRequiredDescription
handlestringyesHandle (@mrbeast), channel id (UC…), or full URL
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/channel/lives?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/channel/lives?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/channel/lives",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/channel/playlists1 creditcacheablebatchable

Channel playlists

Playlists a channel has made public. Pass an id from here to /v1/youtube/playlist for the videos in it.

ParameterTypeRequiredDescription
handlestringyesHandle (@mrbeast), channel id (UC…), or full URL
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/channel/playlists?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/channel/playlists?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/channel/playlists",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/channel/shorts1 creditcacheablebatchable

Channel shorts

A channel's Shorts grid, newest first, about 48 per page. Shorts carry no duration or publish date on this surface — YouTube does not render either — so both are null rather than guessed.

ParameterTypeRequiredDescription
handlestringyesHandle (@mrbeast), channel id (UC…), or full URL
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/channel/shorts?handle=%40mkbhd&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  handle: '@mkbhd',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/channel/shorts?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/channel/shorts",
    params={
        "handle": "@mkbhd",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/community-post1 creditcacheablebatchable

Community post details

One community post by id or permalink, with its full text, attachments and like count. Poll questions and options are under raw. commentCount is null on this surface: the standalone post page does not render one, while /v1/youtube/channel/community-posts does.

ParameterTypeRequiredDescription
urlstringyesPost URL (youtube.com/post/Ugk…) or bare post id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/community-post?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/community-post?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/community-post",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/playlist1 creditcacheablebatchable

Playlist contents

The videos in a public playlist, in playlist order, 100 per page. Playlist metadata (title, description, owner) comes back alongside the items.

ParameterTypeRequiredDescription
playlist_idstringyesPlaylist id (PL…), or any URL containing list=
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/playlist?playlist_id=%3Cplaylist_id%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  playlist_id: '<playlist_id>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/playlist?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/playlist",
    params={
        "playlist_id": "<playlist_id>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/search/hashtag1 creditcacheablebatchable

Search by hashtag

Videos or Shorts carrying a hashtag, as YouTube ranks them on the hashtag landing page. type=shorts switches to the Shorts tab, which is a different result set rather than a filter over the same one.

ParameterTypeRequiredDescription
hashtagstringyesHashtag, with or without the leading #
typeall | shortsnodefaults to all
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/search/hashtag?hashtag=%3Chashtag%3E&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  hashtag: '<hashtag>',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/search/hashtag?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/search/hashtag",
    params={
        "hashtag": "<hashtag>",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/search/typeahead1 creditcacheablebatchable

Search typeahead

YouTube's own search suggestions for a partial query — the autocomplete list the search box shows. Useful as a keyword-research signal: these are ranked by what people actually search for.

ParameterTypeRequiredDescription
querystringyesPartial search query
regionstringnoISO 3166-1 alpha-2 country codedefaults to US
languagestringnoInterface languagedefaults to en

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/search/typeahead?query=ai%20agents&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  query: 'ai agents',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/search/typeahead?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/search/typeahead",
    params={
        "query": "ai agents",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/shorts/trending1 creditcacheablebatchable

Trending shorts

Shorts YouTube is currently surfacing, by region. Note that YouTube retired the global Trending feed — /feed/trending now serves the ordinary home feed — so this reads the ranked Shorts surface instead, which is what still exists. Results differ per request; it is deliberately not subscribable.

ParameterTypeRequiredDescription
regionstringnoISO 3166-1 alpha-2 country codedefaults to US
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/shorts/trending?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/shorts/trending?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/shorts/trending",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/transcript1 creditcacheablebatchable

Video transcript

Full transcript for a YouTube video, as one text block plus timed cues. Returns the requested language when available, otherwise the default track.

ParameterTypeRequiredDescription
urlstringyesVideo URL or 11-character video id
languagestringnoBCP-47 language code, e.g. "en", "es"

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/transcript?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/transcript?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/transcript",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/video1 creditcacheablebatchable

Video or Short details

Public metadata for a YouTube video or Short, including view/like counts.

ParameterTypeRequiredDescription
urlstringyesVideo URL or 11-character video id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/video?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/video?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/video",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/video/comment-replies1 creditcacheablebatchable

Comment replies

Replies to one comment thread. Takes a cursor from the replyCursors list on /v1/youtube/video/comments, or — as a convenience — a video url plus comment_id, in which case we locate the thread on the first comment page for you. **Required:** Pass either cursor (from replyCursors on /v1/youtube/video/comments), or both url and comment_id.

ParameterTypeRequiredDescription
cursorstringnoReply cursor from /v1/youtube/video/comments, or pagination.cursor to page deeper
urlstringnoVideo URL or id — required only when using comment_id
comment_idstringnoTop-level comment id (Ugx…) to fetch replies for

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/video/comment-replies?cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/video/comment-replies?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/video/comment-replies",
    params={
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/video/comments1 creditcacheablebatchable

Video comments

Top-level comments on a video, about 20 per page. Pass pagination.cursor back as cursor for the next page. Each item that has replies also appears in replyCursors; feed that cursor to /v1/youtube/video/comment-replies. Use order=newest when polling for new comments — top is re-ranked by YouTube and will churn.

ParameterTypeRequiredDescription
urlstringyesVideo URL or 11-character video id
ordertop | newestnodefaults to top
cursorstringnopagination.cursor from a previous response

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/video/comments?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/video/comments?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/video/comments",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →

GET/v1/youtube/video/sponsors1 creditcacheablebatchableexperimental

Video sponsors (inferred)

Brands, promo codes and affiliate links inferred from a video's description, plus YouTube's own paid-promotion disclosure. Every signal carries the description line it was read from and a confidence, because this is inference over prose — YouTube publishes no structured sponsor data. Experimental: expect to check evidence before acting on low confidence.

ParameterTypeRequiredDescription
urlstringyesVideo URL or 11-character video id

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl
curl "$API/v1/youtube/video/sponsors?url=8XkPqR2nLvE&cache_max_age=7d" \
  -H "x-api-key: $KEY"
TypeScript
const query = new URLSearchParams({
  url: '8XkPqR2nLvE',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/youtube/video/sponsors?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);
Python
Python
import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/youtube/video/sponsors",
    params={
        "url": "8XkPqR2nLvE",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])
Response codes
200Success
400invalid_request — not charged
401missing_api_key / invalid_api_key / revoked_api_key — never a billing error
402insufficient_credits — the key is valid, the balance is not
429daily_cap_exceeded or upstream_rate_limited — not charged
501not_configured — server is missing credentials or proxies
502upstream_blocked / upstream_schema_drift — not charged
504upstream_timeout — not charged

Run this in the playground →