# 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.

- Page: https://socialtoai.com/docs/api/response/
- Last updated: 2026-10-17

## 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.

### `content` (A 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. |

### `account` (An 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. |

### `comment` (A 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](https://socialtoai.com/docs/api/errors.md) 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](https://socialtoai.com/docs/api/results.md).