Response format
Every SocialToAI call answers in the same shape, whatever the platform: an envelope that says what was called, how it ended and what it cost, around a list of items. There are 28 kinds of item, and each has the same fields on every platform. A field a platform cannot give is null, never missing.
The envelope
schema_version is v1. Clients should ignore fields and codes they do not know.
| Field | Type | What it is |
|---|---|---|
request_id | string | Identifies this call. Quote it when you report a problem. |
schema_version | "v1" | Always "v1". |
fetched_at | string | When the data was read from the platform, ISO 8601 in UTC. |
action | string | The action that ran. |
op | string | The platform-specific interface that ran. Present on call only. (may be absent) |
platform | string | The platform this answer is from. |
target | string | The target this answer is for, as you wrote it. Present when the request names several. (may be absent) |
status | "ok" | "empty" | "error" | "not_supported" | "timeout" | "skipped" | ok, empty, error, not_supported, timeout or skipped. |
reason | string | Why this answer was skipped. Present when status is skipped. (may be absent) |
unavailable | string[] | Field paths this platform cannot give. Those fields are null in every item. |
page.has_more | boolean | true when there is another page. (may be absent) |
page.cursor | string | Send it back as cursor to get the next page. Absent on the last page. (may be absent) |
page.cursor_expires_at | string | When the cursor stops working, ISO 8601 in UTC. (may be absent) |
warnings | array | Things worth knowing that did not fail the call. |
applied_params | object | The parameters as they were applied. |
includes | object | The extra parts you asked for with include, by name: each with its own status and cost_credits. Their fields are filled into the items. (may be absent) |
cost_credits | integer | What this answer cost. 0 when the call failed. |
billing.cost_credits | integer | What the whole request cost. |
billing.balance_credits | integer | Your balance after this call. |
billing.today_spend_credits | integer | Credits spent today, in UTC. |
billing.daily_limit_credits | integer | null | Your daily limit; null when none is set. |
billing.daily_remaining_credits | integer | null | What is left of the daily limit; null when none is set. |
billing.display | string | One sentence an AI can repeat to you. |
replayed | boolean | true when this is a stored result returned again under the same idempotency key: it cost 0. |
replayed_cost_credits | integer | What the first answer cost. Present when replayed is true. (may be absent) |
empty_reason | "no_match" | "filtered" | Why there is nothing: no_match, or filtered by your own conditions. Present when status is empty. (may be absent) |
Statuses
| status | Charged | What it means |
|---|---|---|
ok | Yes | The call worked and items holds the results. |
empty | Yes | The call worked and found nothing. A search that ran and matched nothing is charged as usual. |
error | No | The call failed. error says why and fix says what to do. |
not_supported | No | The platform does not offer this action. |
timeout | No | The result is not known. We do not retry on our own. |
skipped | No | This part was not run. |
Items
Each item says what it is in type. Times are ISO 8601 in UTC. Whoever wrote a comment is never named: comments carry an anonymous label that is stable within one answer.
contentA post, video, note or article
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "content" | The object type. |
url | string | null | A link that opens the item. |
format | "video" | "image" | "text" | "article" | null | video, image, text or article. |
title | string | null | The title. |
text | string | null | The body text or caption. |
published_at | string | null | When it was published, ISO 8601 in UTC. |
author.id | string | null | The author's account ID. |
author.username | string | null | The author's handle. |
author.name | string | null | The author's display name. |
author.verified | boolean | null | Whether the author is verified. |
author.followers | integer | null | The author's follower count. |
metrics.likes | integer | null | Likes. |
metrics.comments | integer | null | Comments. |
metrics.shares | integer | null | Shares. |
metrics.collects | integer | null | Saves. |
metrics.views | integer | null | Views or plays. |
metrics.reposts | integer | null | Reposts. |
images | string[] | null | Image addresses. |
hashtags | string[] | null | Hashtags, without the #. |
is_pinned | boolean | null | Whether the author pinned it. |
accountAn account
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "account" | The object type. |
username | string | null | The handle. |
name | string | null | The display name. |
url | string | null | A link to the profile. |
bio | string | null | The bio. |
verified | boolean | null | Whether the account is verified. |
followers | integer | null | Follower count. |
following | integer | null | How many accounts it follows. |
posts_count | integer | null | How many posts it has published. |
commentA comment
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "comment" | The object type. |
url | string | null | A link to the comment, where the platform has one. |
text | string | null | The comment itself. |
published_at | string | null | When it was posted, ISO 8601 in UTC. |
author.label | string | An anonymous label, stable within one response. Whoever wrote it is never named. |
metrics.likes | integer | null | Likes. |
reply_count | integer | null | How many replies it has. |
content_id | string | null | The item the comment is under. |
parent_id | string | null | The comment it replies to directly; null for a top-level comment. |
root_id | string | null | The top-level comment its thread hangs under. |
entry:trend
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "trend" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields | object | Empty for a trend. |
entry:transcript
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "transcript" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.lang | string | null | The language of the transcript. |
fields.text | string | null | The full text. |
fields.segments | array | null | Timed segments: start, end and text. |
entry:creator_rates
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "creator_rates" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.currency | string | null | The currency of the amounts. |
fields.rates | array | null | What the creator charges: name, amount, settlement and whether it is open. |
entry:community
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "community" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.description | string | null | The community's description. |
fields.nsfw | boolean | null | Whether it is marked as adult content. |
fields.created_at | string | null | When it was created, ISO 8601 in UTC. |
fields.members | integer | null | Member count. |
entry:product
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "product" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.description | string | null | The product description. |
fields.price | string | null | The current price, as a decimal string in fields.currency. |
fields.original_price | string | null | The price before discount. |
fields.currency | string | null | The currency of the prices. |
fields.images | string[] | null | Image addresses. |
fields.rating | number | null | The rating. |
fields.sold | integer | null | Units sold. |
fields.reviews_count | integer | null | How many reviews it has. |
fields.shop.id | string | null | The shop's ID. |
fields.shop.name | string | null | The shop's name. |
entry:review
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "review" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.product_id | string | null | The product the review is about. |
fields.text | string | null | The review itself. |
fields.rating | number | null | The rating given. |
fields.published_at | string | null | When it was posted, ISO 8601 in UTC. |
fields.author.label | string | An anonymous label, stable within one response. Whoever wrote it is never named. |
fields.images | string[] | null | Image addresses. |
fields.variant | string | null | The variant that was bought. |
entry:keyword_history
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "keyword_history" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.points | array | null | One entry per day, oldest first: date, search_index, composite_index, notes, impressions, views, engagements. |
entry:keyword_related
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "keyword_related" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.related_to | string | null | The keyword you asked about. |
fields.relation | "query" | "posts" | "prior" | "after" | null | How it is related: query (searched together with your keyword), posts (appears with it in content), prior (searched before it), after (searched after it). |
fields.relevance | number | null | How closely it is related to your keyword, from 0 to 1. |
fields.search_index | integer | null | The related keyword's search index: the platform's own index, not a count of searches. null where the platform gives no figure for the word. |
fields.composite_index | integer | null | The related keyword's composite index: the platform's own index of how much attention content about it drew, not a count. |
entry:keyword_audience
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "keyword_audience" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.age | array | null | By age group: label, share, tgi. tgi says how over-represented the group is; 100 is average. |
fields.gender | array | null | By gender: label, share, tgi. |
fields.province | array | null | By province: label, share, tgi. |
fields.city | array | null | By city, the largest only, so the shares do not add up to 1: label, share, tgi. |
fields.city_tier | array | null | By city tier: label, share, tgi. |
fields.interest | array | null | By interest. One person can have several, so the shares do not add up to 1: label, share, tgi. |
entry:brand_history
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "brand_history" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.category | string | null | The industry the platform puts the brand in, in the platform's words. |
fields.points | array | null | One entry per day, oldest first: date, search_index, content_index, spread_index. |
entry:brand_metrics
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "brand_metrics" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.category | string | null | The industry the platform puts the brand in, in the platform's words. |
fields.search_index | integer | null | Daily average of the search index over the period. |
fields.content_index | integer | null | Daily average of the content index over the period. |
fields.spread_index | integer | null | Daily average of the spread index over the period. |
fields.benchmarks | array | null | Benchmarks from the same industry: the average of all its brands, and of its top brands. Each has scope, search_index, content_index, spread_index. |
entry:account_history
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "account_history" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.days | integer | null | How many of the most recent days the figures cover. |
fields.gained.followers | integer | null | Net new followers; negative when followers were lost. |
fields.gained.likes | integer | null | New likes. |
fields.gained.comments | integer | null | New comments. |
fields.gained.shares | integer | null | New shares. |
fields.gained.posts | integer | null | Posts published. |
fields.change.followers | number | null | Net new followers compared with the period before, as a ratio. |
fields.change.likes | number | null | New likes compared with the period before, as a ratio. |
fields.change.comments | number | null | New comments compared with the period before, as a ratio. |
fields.change.shares | number | null | New shares compared with the period before, as a ratio. |
fields.change.posts | number | null | Posts published compared with the period before, as a ratio. |
fields.totals.followers | integer | null | Followers now. |
fields.totals.likes | integer | null | Likes received in total. |
fields.totals.posts | integer | null | Posts published in total. |
entry:index_creator_metrics
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "index_creator_metrics" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.average_7d.likes | number | null | New likes a day, on average over the last week. |
fields.average_7d.followers | number | null | New followers a day, on average over the last week. |
fields.average_7d.shares | number | null | New shares a day, on average over the last week. |
fields.average_7d.comments | number | null | New comments a day, on average over the last week. |
fields.average_30d.likes | number | null | New likes a day, on average over the last month. |
fields.average_30d.followers | number | null | New followers a day, on average over the last month. |
fields.average_30d.shares | number | null | New shares a day, on average over the last month. |
fields.average_30d.comments | number | null | New comments a day, on average over the last month. |
fields.change_7d.likes | number | null | New likes a day over the last week compared with the week before, as a ratio. |
fields.change_7d.followers | number | null | New followers a day over the last week compared with the week before, as a ratio. |
fields.change_7d.shares | number | null | New shares a day over the last week compared with the week before, as a ratio. |
fields.change_7d.comments | number | null | New comments a day over the last week compared with the week before, as a ratio. |
fields.change_30d.likes | number | null | New likes a day over the last month compared with the month before, as a ratio. |
fields.change_30d.followers | number | null | New followers a day over the last month compared with the month before, as a ratio. |
fields.change_30d.shares | number | null | New shares a day over the last month compared with the month before, as a ratio. |
fields.change_30d.comments | number | null | New comments a day over the last month compared with the month before, as a ratio. |
entry:creator
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "creator" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.account_id | string | null | The creator's account ID on the platform, which the platform's account calls take. |
fields.username | string | null | The creator's handle. |
fields.location | string | null | Where the creator is based, in the platform's words. |
fields.categories | string[] | null | Content categories, first level, in the platform's words. |
fields.subcategories | string[] | null | Content categories, second level, in the platform's words. |
fields.followers | integer | null | Followers. |
entry:audience
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "audience" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.measured_at | string | null | The day the figures are for, as the start of that day in China time (UTC+8). |
fields.gender | array | null | By gender: name, share, count. |
fields.age | array | null | By age group: name, share, count. |
fields.province | array | null | By province: name, share, count. |
fields.city | array | null | By city, the largest only: name, share, count. |
fields.interest | array | null | By interest: name, share, count. |
fields.device | array | null | By phone brand: name, share, count. |
fields.city_tier | array | null | By city tier: name, share, count. |
fields.crowd | array | null | By the consumer groups the platform sorts people into: name, share, count. |
fields.purchase_category | array | null | By category of goods bought: name, share, count. |
fields.purchase_amount | array | null | By amount spent per order: name, share, count. |
entry:xingtu_creator_metrics
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "xingtu_creator_metrics" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.videos | integer | null | Videos in the period. |
fields.median_views | integer | null | Median views per video. |
fields.average_likes | integer | null | Average likes per video. |
fields.average_comments | integer | null | Average comments per video. |
fields.average_shares | integer | null | Average shares per video. |
fields.engagement_rate | number | null | Engagement rate, 0 to 1. |
fields.engagement_rate_percentile | number | null | The share of comparable creators this engagement rate beats, 0 to 1. |
fields.completion_rate | number | null | Completion rate, 0 to 1. |
fields.completion_rate_percentile | number | null | The share of comparable creators this completion rate beats, 0 to 1. |
fields.currency | string | null | The currency of the four costs below. |
fields.cpm_21_60s | string | null | Expected cost per thousand views of a 21 to 60 second video. |
fields.cpm_over_60s | string | null | Expected cost per thousand views of a video over 60 seconds. |
fields.cpe_21_60s | string | null | Expected cost per interaction of a 21 to 60 second video. |
fields.cpe_over_60s | string | null | Expected cost per interaction of a video over 60 seconds. |
entry:xingtu_creator_post
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "xingtu_creator_post" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.published_at | string | null | When it was published. |
fields.duration | number | null | Length of the video, in seconds. |
fields.views | integer | null | Views. |
fields.likes | integer | null | Likes. |
fields.comments | integer | null | Comments. |
fields.completion_rate | number | null | Completion rate, 0 to 1. |
fields.engagement_rate | number | null | Engagement rate, 0 to 1. |
entry:xingtu_creator_keywords
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "xingtu_creator_keywords" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.keywords | array | null | The words that come up most, one entry each: keyword, mentions. |
entry:xingtu_creator_scores
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "xingtu_creator_scores" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.overall.score | number | null | The overall Xingtu score, 0 to 100. |
fields.overall.average | number | null | What comparable creators average on the overall Xingtu score. |
fields.overall.rank | integer | null | The creator's rank on the overall Xingtu score; 1 is the highest. |
fields.overall.rank_share | number | null | How near the top that rank is, 0 to 1: 0.05 means the top 5%. |
fields.reach.score | number | null | The reach score, 0 to 100. |
fields.reach.average | number | null | What comparable creators average on the reach score. |
fields.reach.rank | integer | null | The creator's rank on the reach score; 1 is the highest. |
fields.reach.rank_share | number | null | How near the top that rank is, 0 to 1: 0.05 means the top 5%. |
fields.seeding.score | number | null | The seeding score, 0 to 100. |
fields.seeding.average | number | null | What comparable creators average on the seeding score. |
fields.seeding.rank | integer | null | The creator's rank on the seeding score; 1 is the highest. |
fields.seeding.rank_share | number | null | How near the top that rank is, 0 to 1: 0.05 means the top 5%. |
fields.conversion.score | number | null | The conversion score, 0 to 100. |
fields.conversion.average | number | null | What comparable creators average on the conversion score. |
fields.conversion.rank | integer | null | The creator's rank on the conversion score; 1 is the highest. |
fields.conversion.rank_share | number | null | How near the top that rank is, 0 to 1: 0.05 means the top 5%. |
fields.cooperation.score | number | null | The cooperation score, 0 to 100. |
fields.cooperation.average | number | null | What comparable creators average on the cooperation score. |
fields.cooperation.rank | integer | null | The creator's rank on the cooperation score; 1 is the highest. |
fields.cooperation.rank_share | number | null | How near the top that rank is, 0 to 1: 0.05 means the top 5%. |
fields.value_for_money.score | number | null | The value-for-money score, 0 to 100. |
fields.value_for_money.average | number | null | What comparable creators average on the value-for-money score. |
fields.value_for_money.rank | integer | null | The creator's rank on the value-for-money score; 1 is the highest. |
fields.value_for_money.rank_share | number | null | How near the top that rank is, 0 to 1: 0.05 means the top 5%. |
entry:xingtu_creator_content_mix
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "xingtu_creator_content_mix" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.categories | array | null | The content categories, one entry each: name, share, videos. |
entry:xingtu_campaign
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "xingtu_campaign" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.description | string | null | What the campaign is. |
fields.category | "platform_event" | "ecommerce" | "seasonal" | "creative" | "industry" | null | The kind of campaign: a platform event, an e-commerce date, a seasonal or mood moment, creative marketing, or an industry campaign. |
fields.stage | "preparing" | "open" | "live" | "ended" | null | How far along the campaign is: in preparation, open for sign-up, live, or ended. |
fields.signup_starts_at | string | null | When sign-up opens. |
fields.signup_ends_at | string | null | When sign-up closes. |
fields.starts_at | string | null | When the campaign starts. |
fields.ends_at | string | null | When the campaign ends. |
fields.image_url | string | null | The campaign's main image. |
entry:ad
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "ad" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.format | "video" | "image" | "carousel" | "text" | "other" | null | The ad's format: text, image or video. other is a format of the platform's own. |
fields.text | string | null | The ad's body text. |
fields.landing_url | string | null | Where a click on the ad leads. |
fields.advertiser.id | string | null | Advertiser ID. |
fields.advertiser.name | string | null | Advertiser's name. |
fields.advertiser.url | string | null | The advertiser's page on the platform. |
fields.images | string[] | null | Addresses of the ad's images. |
fields.first_shown_at | string | null | When the ad was first shown. |
fields.last_shown_at | string | null | When the ad was last shown. For an ad still running, when the platform last saw it. |
entry:advertiser
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "advertiser" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.region | string | null | The code of the country or region the advertiser is registered in. |
entry:channels_collection
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "channels_collection" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.description | string | null | The collection's own description; null when it has none. |
fields.cover_url | string | null | Address of the collection's cover image. |
fields.updated_at | string | null | When the collection was last updated. |
fields.videos | integer | null | Videos in the collection. |
entry:topic
| Field | Type | What it is |
|---|---|---|
platform | string | The platform the item is from. |
id | string | null | The platform's own ID. |
ref | string | null | What to send back in a request to point at this item. |
approx | array | Which numbers of this item are approximate or lower bounds; empty when all are exact. |
type | "entry" | The object type. |
entry_type | "topic" | What kind of entry this is. |
title | string | null | The entry's title or name. |
url | string | null | A link that opens it; null where the platform's list has none. |
rank | integer | null | Position on a board, from 1. |
heat | integer | null | The platform's heat score. |
fields.description | string | null | The topic's own description; null when it has none. |
fields.views | integer | null | Views of the topic. |
fields.posts | integer | null | Posts under the topic. |
The error structure
A request that fails as a whole answers with this instead of the envelope, under the HTTP status of its code. A result that fails inside a 200 answer carries the same error object.
| Field | Type | What it is |
|---|---|---|
request_id | string | Identifies this call. Quote it when you report a problem. |
schema_version | "v1" | Always "v1". |
error.code | string | The error code: one row of the error table. |
error.message | string | What went wrong, in Chinese and in English. |
error.retryable | boolean | Whether sending the same request again can work. |
error.reason | string | Which case of the code this is, where a code has several. (may be absent) |
error.quote_credits | integer | What the refused request would have cost. (may be absent) |
error.resets_at | string | When a daily limit starts again, ISO 8601 in UTC. (may be absent) |
error.retry_at | string | After free_failure_limit: from when a call may be sent again, ISO 8601 in UTC. (may be absent) |
error.fix.param | string | The parameter to correct. (may be absent) |
error.fix.allowed | array | The values that parameter may take. (may be absent) |
error.fix.example_call | object | A call that would work, ready to copy. It never repeats a key. (may be absent) |
error.fix.action_url | string | Where to go to fix it: the console, billing or the status page. (may be absent) |
error.fix.note | string | What to do, in a sentence. (may be absent) |
billing.cost_credits | integer | Always 0: a failed request is not charged. (may be absent) |
billing.balance_credits | integer | Your balance. Present when the key is known. (may be absent) |
billing.today_spend_credits | integer | Credits spent today, in UTC. (may be absent) |
billing.daily_limit_credits | integer | null | Your daily limit; null when none is set. (may be absent) |
billing.daily_remaining_credits | integer | null | What is left of the daily limit; null when none is set. (may be absent) |
billing.display | string | One sentence an AI can repeat to you. (may be absent) |
Errors lists every code.
When the answer is not ready
A call that cannot answer within its request answers HTTP 202 with a handle instead of this envelope, and the envelope is read with the handle afterwards. See Results and handles.
Last updated: