Every endpoint returns one of these models in data. The same field names mean the same thing on every platform. A field the platform does not provide is null, never invented; platform details with no field of their own are in extra. Pass trim=true to drop null fields and extra, or raw=true to also get the platform's original object next to data.
Lists#
Every list endpoint returns a list object. See Pagination.
| Field | Type | Notes |
|---|
object | "list" | |
items | array | The page of results; the type depends on the endpoint. |
cursor | string or null | Pass it back unchanged for the next page. null on the last page. |
has_more | boolean | Whether another page exists. |
parent | object or null | The thing the list belongs to (a profile for its posts), where the platform returns it. |
Activity#
One public activity event (GitHub events).
| Field | Type | Required | Notes |
|---|
object | "activity" | | |
platform | Platform | yes | |
id | string | yes | |
type | string | yes | platform's event type, snake_case: "push", "pull_request", "star" |
actor | Author or null | | |
repo | string or null | | |
created_at | string (ISO 8601 date-time) or null | | |
extra | object or null | | |
| Field | Type | Required | Notes |
|---|
object | "ad" | | |
platform | Platform | yes | the ad library's platform |
id | string | yes | |
url | string or null | | |
advertiser | Advertiser or null | | |
status | "active" or "inactive" or "unknown" | | |
started_at | string (ISO 8601 date-time) or null | | |
ended_at | string (ISO 8601 date-time) or null | | |
title | string or null | | |
body | string or null | | |
cta_text | string or null | | |
landing_url | string or null | | |
format | string or null | | "image" | "video" | "carousel" | "text" | platform-specific |
media | Media | | |
regions | string[] or null | | |
publisher_platforms | string[] or null | | where it ran: facebook, instagram, ... |
impressions | Range or null | | |
spend | Range or null | | |
extra | object or null | | |
Advertiser#
| Field | Type | Required | Notes |
|---|
object | "advertiser" | | |
platform | Platform | yes | the ad library's platform |
id | string or null | | |
name | string or null | | |
url | string or null | | |
page_id | string or null | | |
country | string or null | | |
verified | boolean or null | | |
ad_count | integer or null | | |
extra | object or null | | |
Album#
| Field | Type | Required | Notes |
|---|
object | "album" | | |
platform | Platform | yes | |
id | string | yes | |
url | string or null | | |
title | string or null | | |
artists | string[] or null | | |
released_at | string (ISO 8601 date) or null | | |
track_count | integer or null | | |
cover_url | string or null | | |
label | string or null | | |
tracks | Song[] or null | | |
extra | object or null | | |
Author#
Compact reference to a profile, embedded in posts, comments, ads.
| Field | Type | Required | Notes |
|---|
id | string or null | | |
handle | string or null | | |
name | string or null | | |
url | string or null | | |
avatar_url | string or null | | |
verified | boolean or null | | |
BatchItem#
One envelope per batch request, in order. response is a full envelope.
| Field | Type | Required | Notes |
|---|
path | string | yes | |
status | integer | yes | |
response | object | yes | |
BatchResult#
| Field | Type | Required | Notes |
|---|
object | "batch" | | |
results | BatchItem[] | yes | |
Collection#
An ordered set of items someone curates: playlists, boards, podcasts, highlights.
| Field | Type | Required | Notes |
|---|
object | "collection" | | |
platform | Platform | yes | |
id | string | yes | |
url | string or null | | |
kind | "playlist" or "board" or "podcast" or "highlight" or "topic" or "collection" or "unknown" | | |
title | string or null | | |
description | string or null | | |
owner | Author or null | | |
item_count | integer or null | | |
cover_url | string or null | | |
updated_at | string (ISO 8601 date-time) or null | | |
extra | object or null | | |
| Field | Type | Required | Notes |
|---|
object | "comment" | | |
platform | Platform | yes | |
id | string | yes | |
url | string or null | | |
post_id | string or null | | |
parent_id | string or null | | set on replies |
author | Author or null | | |
text | string or null | | |
published_at | string (ISO 8601 date-time) or null | | |
stats | CommentStats | | |
is_pinned | boolean or null | | |
is_by_creator | boolean or null | | |
extra | object or null | | |
| Field | Type | Required | Notes |
|---|
likes | integer or null | | |
replies | integer or null | | |
dislikes | integer or null | | |
A place people post into: subreddits, Facebook groups, X communities, Telegram channels.
| Field | Type | Required | Notes |
|---|
object | "community" | | |
platform | Platform | yes | |
id | string or null | | |
url | string or null | | |
kind | "subreddit" or "group" or "community" or "channel" or "unknown" | | |
name | string or null | | the slug, "python" for r/python |
title | string or null | | |
description | string or null | | |
avatar_url | string or null | | |
banner_url | string or null | | |
member_count | integer or null | | |
online_count | integer or null | | |
is_nsfw | boolean or null | | |
is_private | boolean or null | | |
verified | boolean or null | | the platform's verified badge (Telegram channels) |
created_at | string (ISO 8601 date-time) or null | | |
extra | object or null | | |
ContributionDay#
| Field | Type | Required | Notes |
|---|
date | string (ISO 8601 date) | yes | |
count | integer | yes | |
Contributions#
| Field | Type | Required | Notes |
|---|
object | "contributions" | | |
platform | Platform | yes | |
handle | string or null | | |
total | integer or null | | |
days | ContributionDay[] or null | | |
extra | object or null | | |
CreatorEmails#
Listed emails for a creator, each with where it was found.
| Field | Type | Required | Notes |
|---|
object | "creator_emails" | | |
platform | Platform | yes | the platform of the profile that was asked about |
handle | string or null | | |
profile_url | string or null | | |
emails | FoundEmail[] | yes | |
extra | object or null | | |
CreditBalance#
| Field | Type | Required | Notes |
|---|
object | "credit_balance" | | |
credits_remaining | integer | yes | |
team_id | string | yes | |
Embed#
| Field | Type | Required | Notes |
|---|
object | "embed" | | |
platform | Platform | yes | |
url | string or null | | |
html | string | yes | |
extra | object or null | | |
Event#
| Field | Type | Required | Notes |
|---|
object | "event" | | |
platform | Platform | yes | |
id | string | yes | |
url | string or null | | |
title | string or null | | |
description | string or null | | |
starts_at | string (ISO 8601 date-time) or null | | |
ends_at | string (ISO 8601 date-time) or null | | |
place | Place or null | | |
is_online | boolean or null | | |
host | Author or null | | |
going_count | integer or null | | |
interested_count | integer or null | | |
cover_url | string or null | | |
extra | object or null | | |
FoundEmail#
| Field | Type | Required | Notes |
|---|
email | string | yes | |
source_url | string or null | | where it was published |
kind | string or null | | "business" | "management" | "personal" | ... |
JobAccepted#
Answer for a job that is still running. Poll poll_url (free).
| Field | Type | Required | Notes |
|---|
object | "job" | | |
job_id | string | yes | |
status | "pending" or "running" | yes | |
poll_url | string | yes | |
Link#
| Field | Type | Required | Notes |
|---|
title | string or null | | |
url | string | yes | |
LinkPage#
A link-in-bio page (Linktree, Komi, Pillar, Linkbio, Linkme).
| Field | Type | Required | Notes |
|---|
object | "link_page" | | |
platform | Platform | yes | |
handle | string or null | | |
url | string or null | | |
name | string or null | | |
bio | string or null | | |
avatar_url | string or null | | |
links | Link[] or null | | |
socials | Link[] or null | | title = platform name |
extra | object or null | | |
LiveStream#
| Field | Type | Required | Notes |
|---|
object | "live_stream" | | |
platform | Platform | yes | |
is_live | boolean | yes | |
id | string or null | | room / stream id |
url | string or null | | |
author | Author or null | | |
title | string or null | | |
viewer_count | integer or null | | |
like_count | integer or null | | |
started_at | string (ISO 8601 date-time) or null | | |
cover_url | string or null | | |
extra | object or null | | |
Location#
A named place with coordinates (Facebook Marketplace city search).
| Field | Type | Required | Notes |
|---|
object | "location" | | |
platform | Platform | yes | |
id | string or null | | |
name | string | yes | |
region | string or null | | state / province |
country | string or null | | ISO 3166-1 alpha-2 when known |
latitude | number or null | | |
longitude | number or null | | |
extra | object or null | | |
| Field | Type | Required | Notes |
|---|
thumbnail_url | string or null | | |
video_url | string or null | | |
audio_url | string or null | | |
image_urls | string[] or null | | |
width | integer or null | | |
height | integer or null | | |
Monitor#
| Field | Type | Required | Notes |
|---|
object | "monitor" | | |
id | string | yes | |
endpoint | string | yes | endpoint path it watches, "/v1/tiktok/profile/videos" |
params | object | yes | |
interval_minutes | integer | yes | |
webhook_url | string | yes | |
active | boolean | yes | false: deleted, or paused after repeated failures (last_error says why) |
created_at | string (ISO 8601 date-time) | yes | |
webhook_secret | string or null | | |
last_run_at | string (ISO 8601 date-time) or null | | |
next_run_at | string (ISO 8601 date-time) or null | | |
last_error | string or null | | error code of the last failed run, "insufficient_credits", ... |
MonitorEvent#
| Field | Type | Required | Notes |
|---|
object | "monitor_event" | | |
id | string | yes | |
monitor_id | string | yes | |
type | "new_items" | yes | |
items | object[] | yes | normalised objects, as the watched endpoint returns them |
created_at | string (ISO 8601 date-time) | yes | |
Place#
| Field | Type | Required | Notes |
|---|
name | string or null | | |
address | string or null | | |
city | string or null | | |
region | string or null | | |
country | string or null | | ISO 3166-1 alpha-2 when known |
latitude | number or null | | |
longitude | number or null | | |
Post#
Videos, reels, tweets, pins, clips, stories, Reddit posts: all posts with a type.
| Field | Type | Required | Notes |
|---|
object | "post" | | |
platform | Platform | yes | |
id | string | yes | |
url | string or null | | |
type | "video" or "short" or "reel" or "image" or "carousel" or "story" or "live" or "clip" or "text" or "link" or "tweet" or "pin" or "community_post" or "episode" or "unknown" | | |
author | Author or null | | |
title | string or null | | |
text | string or null | | |
published_at | string (ISO 8601 date-time) or null | | |
duration_seconds | number or null | | |
language | string or null | | |
hashtags | string[] or null | | |
mentions | string[] or null | | |
stats | Stats | | |
media | Media | | |
song | SongRef or null | | |
location | Place or null | | |
is_pinned | boolean or null | | |
is_sponsored | boolean or null | | |
extra | object or null | | |
Price#
| Field | Type | Required | Notes |
|---|
amount | number or null | | |
currency | string or null | | ISO 4217 |
original_amount | number or null | | before a discount |
display | string or null | | as the platform shows it, "$12.99" |
Product#
Shop products and marketplace listings.
| Field | Type | Required | Notes |
|---|
object | "product" | | |
platform | Platform | yes | |
id | string | yes | |
url | string or null | | |
title | string or null | | |
description | string or null | | |
price | Price or null | | |
seller | Author or null | | |
rating | number or null | | |
review_count | integer or null | | |
sold_count | integer or null | | |
image_urls | string[] or null | | |
category | string or null | | |
in_stock | boolean or null | | |
location | Place or null | | |
published_at | string (ISO 8601 date-time) or null | | |
extra | object or null | | |
Profile#
| Field | Type | Required | Notes |
|---|
object | "profile" | | |
platform | Platform | yes | |
id | string or null | | |
handle | string or null | | |
name | string or null | | |
headline | string or null | | a short tagline apart from the bio (LinkedIn's headline) |
url | string or null | | |
kind | "person" or "creator" or "channel" or "page" or "company" or "artist" or "organization" or "shop" or "unknown" | | |
bio | string or null | | |
avatar_url | string or null | | |
banner_url | string or null | | |
verified | boolean or null | | |
is_private | boolean or null | | |
external_url | string or null | | |
links | Link[] or null | | |
location | string or null | | |
category | string or null | | |
created_at | string (ISO 8601 date-time) or null | | |
stats | ProfileStats | | |
extra | object or null | | |
ProfileStats#
| Field | Type | Required | Notes |
|---|
followers | integer or null | | |
following | integer or null | | |
posts | integer or null | | |
likes | integer or null | | |
views | integer or null | | |
PullRequest#
| Field | Type | Required | Notes |
|---|
object | "pull_request" | | |
platform | Platform | yes | |
id | string | yes | |
url | string or null | | |
repo | string or null | | "owner/name" |
number | integer or null | | |
title | string or null | | |
state | "open" or "closed" or "merged" or "unknown" | | |
author | Author or null | | |
created_at | string (ISO 8601 date-time) or null | | |
closed_at | string (ISO 8601 date-time) or null | | |
merged_at | string (ISO 8601 date-time) or null | | |
extra | object or null | | |
Range#
A bounded estimate as ad libraries publish them (impressions, spend).
| Field | Type | Required | Notes |
|---|
lower | number or null | | |
upper | number or null | | |
currency | string or null | | |
Repo#
| Field | Type | Required | Notes |
|---|
object | "repo" | | |
platform | Platform | yes | |
id | string or null | | |
full_name | string | yes | "owner/name" |
name | string or null | | |
url | string or null | | |
owner | Author or null | | |
description | string or null | | |
language | string or null | | |
topics | string[] or null | | |
license | string or null | | |
stars | integer or null | | |
forks | integer or null | | |
watchers | integer or null | | |
open_issues | integer or null | | |
is_fork | boolean or null | | |
is_archived | boolean or null | | |
default_branch | string or null | | |
created_at | string (ISO 8601 date-time) or null | | |
updated_at | string (ISO 8601 date-time) or null | | |
pushed_at | string (ISO 8601 date-time) or null | | |
extra | object or null | | |
RequestLogEntry#
One past API request of the team (account request history).
| Field | Type | Required | Notes |
|---|
object | "request_log" | | |
request_id | string | yes | |
endpoint | string | yes | the path that was called, "/v1/tiktok/profile" |
endpoint_id | string or null | | |
status | integer | yes | |
credits_charged | integer | yes | |
cached | boolean or null | | |
created_at | string (ISO 8601 date-time) | yes | |
Review#
| Field | Type | Required | Notes |
|---|
object | "review" | | |
platform | Platform | yes | |
id | string | yes | |
product_id | string or null | | |
author | Author or null | | |
rating | number or null | | |
text | string or null | | |
published_at | string (ISO 8601 date-time) or null | | |
image_urls | string[] or null | | |
extra | object or null | | |
SearchResult#
One organic web search result (Google search).
| Field | Type | Required | Notes |
|---|
object | "search_result" | | |
platform | Platform | yes | |
position | integer or null | | |
title | string or null | | |
url | string | yes | |
displayed_url | string or null | | |
snippet | string or null | | |
kind | string or null | | "organic" | "video" | "news" | ... |
extra | object or null | | |
Song#
A sound or music track (TikTok sounds, Spotify/Apple/SoundCloud tracks).
| Field | Type | Required | Notes |
|---|
object | "song" | | |
platform | Platform | yes | |
id | string | yes | |
url | string or null | | |
title | string or null | | |
artists | string[] or null | | |
album | string or null | | |
duration_seconds | number or null | | |
cover_url | string or null | | |
preview_url | string or null | | |
released_at | string (ISO 8601 date) or null | | |
isrc | string or null | | |
explicit | boolean or null | | |
is_original | boolean or null | | TikTok "original sound" |
stats | SongStats | | |
extra | object or null | | |
SongRef#
The sound used by a post (TikTok, Reels, Shorts).
| Field | Type | Required | Notes |
|---|
id | string or null | | |
title | string or null | | |
artist | string or null | | |
url | string or null | | |
SongStats#
| Field | Type | Required | Notes |
|---|
plays | integer or null | | |
uses | integer or null | | videos made with the sound |
likes | integer or null | | |
Stats#
Engagement on a post. Same five names on every platform.
| Field | Type | Required | Notes |
|---|
views | integer or null | | |
likes | integer or null | | |
comments | integer or null | | |
shares | integer or null | | |
saves | integer or null | | |
dislikes | integer or null | | where the platform shows them (Rumble) |
Suggestion#
One search suggestion or typeahead entry (TikTok, YouTube, Instagram).
| Field | Type | Required | Notes |
|---|
object | "suggestion" | | |
platform | Platform | yes | |
kind | "query" or "channel" or "user" or "hashtag" or "place" or "product" or "unknown" | | |
text | string | yes | |
id | string or null | | channel / user / hashtag / place id when the platform gives one |
handle | string or null | | |
url | string or null | | |
image_url | string or null | | |
verified | boolean or null | | |
extra | object or null | | |
Transcript#
| Field | Type | Required | Notes |
|---|
object | "transcript" | | |
platform | Platform | yes | |
video_id | string or null | | |
url | string or null | | |
language | string or null | | BCP 47, "en" |
source | "captions" or "auto_captions" or "ai" | yes | |
duration_seconds | number or null | | |
text | string | yes | |
segments | TranscriptSegment[] or null | | |
available_languages | string[] or null | | |
extra | object or null | | |
TranscriptSegment#
| Field | Type | Required | Notes |
|---|
start | number | yes | seconds |
end | number or null | | |
text | string | yes | |
UsageStat#
Aggregated usage: one day (date set) or one endpoint (endpoint set).
| Field | Type | Required | Notes |
|---|
object | "usage_stat" | | |
date | string (ISO 8601 date) or null | | |
endpoint | string or null | | |
requests | integer | yes | |
credits_charged | integer | yes | |
WebhookDelivery#
One delivery attempt of a monitor event.
| Field | Type | Required | Notes |
|---|
object | "webhook_delivery" | | |
event_id | string | yes | |
monitor_id | string | yes | |
attempt | integer | yes | |
status_code | integer or null | | |
ok | boolean | yes | |
dead_letter | boolean | yes | the last attempt of a chain that gave up; redeliver to try again |
error | string or null | | |
created_at | string (ISO 8601 date-time) | yes | |
WebhookRedelivery#
| Field | Type | Required | Notes |
|---|
object | "webhook_redelivery" | | |
event_id | string | yes | |
queued | boolean | yes | |
previous_state | "pending" or "retrying" or "dead" | yes | |
WebhookTest#
What the receiver answered to a signed test event ("type": "test").
| Field | Type | Required | Notes |
|---|
object | "webhook_test" | | |
monitor_id | string | yes | |
delivered | boolean | yes | |
status_code | integer or null | | |
error | string or null | | |
Allowed values: youtube, tiktok, instagram, reddit, bluesky, threads, truthsocial, pinterest, twitch, kick, snapchat, linktree, komi, pillar, linkbio, linkme, twitter, facebook, linkedin, amazon, spotify, apple_music, soundcloud, github, kwai, rumble, telegram, google, cosmos, web.