---
title: "Response format · Docs · SocialToAI"
canonical: https://socialtoai.app/docs/api/response/
updated: 2026-11-20
---

# 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 38 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.app/docs/api/response/
- Last updated: 2026-11-20

## 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) |
| `watch_hint` | string | One line that offers to run this every day, at most once an hour. Over HTTP only when the same target is asked for again, with the request that makes the schedule. (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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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" \| "suggestion" \| 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), suggestion (offered as your keyword is typed into the search box). |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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.follows` | number \| null | Follows a day, on average over the last week, as the platform counts them: not the net gain in followers, larger, and positive even when followers were lost. |
| `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.follows` | number \| null | Follows a day, on average over the last month, as the platform counts them (not the net gain in followers). |
| `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.follows` | number \| null | Follows 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.follows` | number \| null | Follows 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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. Counted only of videos by a Xingtu creator published about 2023 or later: 0 may mean there is none. |
| `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_integrated` | string \| null | Expected cost per thousand views of an integrated video (the brand worked into the creator's own video). |
| `fields.cpm_custom` | string \| null | Expected cost per thousand views of a custom video (made for the brand). |
| `fields.cpe_integrated` | string \| null | Expected cost per interaction of an integrated video. |
| `fields.cpe_custom` | string \| null | Expected cost per interaction of a custom video. |

### `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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:pgy_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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `type` | "entry" | The object type. |
| `entry_type` | "pgy_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.notes` | integer \| null | Notes in the period. |
| `fields.median_impressions` | integer \| null | Median impressions per note. |
| `fields.median_reads` | integer \| null | Median reads per note. |
| `fields.median_engagements` | integer \| null | Median interactions per note. |
| `fields.median_likes` | integer \| null | Median likes per note. |
| `fields.median_collects` | integer \| null | Median saves per note. |
| `fields.median_comments` | integer \| null | Median comments per note. |
| `fields.median_shares` | integer \| null | Median shares per note. |
| `fields.engagement_rate` | number \| null | Engagement rate, 0 to 1. |
| `fields.video_completion_rate` | number \| null | Completion rate of video notes, 0 to 1. |
| `fields.image_3s_read_rate` | number \| null | Share of image-note reads that last 3 seconds, 0 to 1. |
| `fields.hundred_like_share` | number \| null | Share of notes with 100 likes or more, 0 to 1. |
| `fields.thousand_like_share` | number \| null | Share of notes with 1,000 likes or more, 0 to 1. |
| `fields.impressions_percentile` | number \| null | The share of comparable creators this median of impressions beats, 0 to 1. |
| `fields.reads_percentile` | number \| null | The share of comparable creators this median of reads beats, 0 to 1. |
| `fields.engagements_percentile` | number \| null | The share of comparable creators this median of interactions beats, 0 to 1. |

### `entry:pgy_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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `type` | "entry" | The object type. |
| `entry_type` | "pgy_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.format` | "image" \| "video" \| null | image for an image note, video for a video note. |
| `fields.published_at` | string \| null | The day it was published. The platform gives the day only, shown as the start of that day in China time (UTC+8). |
| `fields.cover_url` | string \| null | Address of the cover image. |
| `fields.is_sponsored` | boolean \| null | Whether it is a sponsored note: one with a brand. |
| `fields.is_promoted` | boolean \| null | Whether it carried paid promotion traffic. Sponsored or not has nothing to do with it. |
| `fields.brand` | string \| null | The brand it was made for, in the platform's words; null when the note is not sponsored. |
| `fields.views` | integer \| null | Reads. |
| `fields.likes` | integer \| null | Likes. |
| `fields.collects` | integer \| null | Saves. |

### `entry:pgy_creator_costs`

| 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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `type` | "entry" | The object type. |
| `entry_type` | "pgy_creator_costs" | 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.date` | string \| null | The day the figures are of: a day in China time, as midnight UTC of its date. |
| `fields.currency` | string \| null | The currency of the costs. |
| `fields.image_cpm` | string \| null | Estimated CPM of an image note; null where the marketplace has no estimate. |
| `fields.image_cpm_percentile` | number \| null | The share of comparable creators whose cost is higher, 0 to 1. |
| `fields.video_cpm` | string \| null | Estimated CPM of a video note; null where the marketplace has no estimate. |
| `fields.video_cpm_percentile` | number \| null | The share of comparable creators whose cost is higher, 0 to 1. |
| `fields.image_cpe` | string \| null | Estimated cost per interaction of an image note; null where the marketplace has no estimate. |
| `fields.image_cpe_percentile` | number \| null | The share of comparable creators whose cost is higher, 0 to 1. |
| `fields.video_cpe` | string \| null | Estimated cost per interaction of a video note; null where the marketplace has no estimate. |
| `fields.video_cpe_percentile` | number \| null | The share of comparable creators whose cost is higher, 0 to 1. |
| `fields.image_read_cost` | string \| null | Estimated cost per read of an image note; null where the marketplace has no estimate. |
| `fields.image_read_cost_percentile` | number \| null | The share of comparable creators whose cost is higher, 0 to 1. |
| `fields.video_read_cost` | string \| null | Estimated cost per read of a video note; null where the marketplace has no estimate. |
| `fields.video_read_cost_percentile` | number \| null | The share of comparable creators whose cost is higher, 0 to 1. |
| `fields.image_shop_visit_cost` | string \| null | Estimated cost per shop visitor an image note brings; null where the marketplace has no estimate. |
| `fields.image_shop_visit_cost_percentile` | number \| null | The share of comparable creators whose cost is higher, 0 to 1. |
| `fields.video_shop_visit_cost` | string \| null | Estimated cost per shop visitor a video note brings; null where the marketplace has no estimate. |
| `fields.video_shop_visit_cost_percentile` | number \| null | The share of comparable creators whose cost is higher, 0 to 1. |
| `fields.median_impressions` | integer \| null | Median impressions of a note. |
| `fields.median_impressions_percentile` | number \| null | The share of comparable creators it exceeds, 0 to 1. |
| `fields.median_reads` | integer \| null | Median reads of a note. |
| `fields.median_reads_percentile` | number \| null | The share of comparable creators it exceeds, 0 to 1. |
| `fields.median_engagements` | integer \| null | Median interactions of a note. |
| `fields.median_engagements_percentile` | number \| null | The share of comparable creators it exceeds, 0 to 1. |
| `fields.median_shop_visits` | integer \| null | Median shop visitors a note brings. |
| `fields.median_shop_visits_percentile` | number \| null | The share of comparable creators it exceeds, 0 to 1. |
| `fields.follower_growth` | number \| null | Follower growth over the last 30 days: 0.037 is 3.7% more; negative when followers were lost. |
| `fields.follower_growth_percentile` | number \| null | The share of comparable creators it exceeds, 0 to 1. |
| `fields.invite_reply_rate` | number \| null | The share of invitations answered within 48 hours, 0 to 1. |
| `fields.easy_to_reach` | boolean \| null | Whether the marketplace marks the creator easy to reach. |
| `fields.active_days_7d` | integer \| null | Days active of the last 7. |
| `fields.is_active` | boolean \| null | Whether the marketplace marks the creator active. |
| `fields.notes_30d` | integer \| null | Notes published over the last 30 days, everyday and sponsored. |
| `fields.highlight` | string \| null | The strength the marketplace marks, in its words; null when none. |
| `fields.highlight_reason` | string \| null | What that strength rests on, in its words. |
| `fields.content_mix` | array \| null | The kinds of content and their shares, the largest first: category, share. |
| `fields.industries` | string[] \| null | Industries worked with, in the platform's words. |

### `entry:pgy_creator_followers`

| 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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `type` | "entry" | The object type. |
| `entry_type` | "pgy_creator_followers" | 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.followers` | integer \| null | Followers. |
| `fields.gained` | integer \| null | Net followers gained over the last 30 days; negative when followers were lost. |
| `fields.growth` | number \| null | Follower growth over the last 30 days: 0.008 is 0.8% more. |
| `fields.growth_percentile` | number \| null | The share of comparable creators it exceeds, 0 to 1. |
| `fields.active_followers` | integer \| null | Followers active on the platform in the last 28 days. |
| `fields.active_share` | number \| null | Their share of all followers, 0 to 1. |
| `fields.active_percentile` | number \| null | The share of comparable creators that share exceeds, 0 to 1. |
| `fields.engaged_followers` | integer \| null | Followers who interacted with the creator's notes in the last 30 days. |
| `fields.engaged_share` | number \| null | Their share of all followers, 0 to 1. |
| `fields.engaged_percentile` | number \| null | The share of comparable creators that share exceeds, 0 to 1. |
| `fields.reading_followers` | integer \| null | Followers who read the creator's notes in the last 30 days. |
| `fields.reading_share` | number \| null | Their share of all followers, 0 to 1. |
| `fields.reading_percentile` | number \| null | The share of comparable creators that share exceeds, 0 to 1. |
| `fields.buying_followers` | integer \| null | Followers who bought something on the platform in the last 30 days. |
| `fields.buying_share` | number \| null | Their share of all followers, 0 to 1. |

### `entry:pgy_creator_cost_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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `type` | "entry" | The object type. |
| `entry_type` | "pgy_creator_cost_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.currency` | string \| null | The currency of the costs. |
| `fields.date` | string \| null | The day the period's figures run to, as midnight UTC of its date in China time. |
| `fields.cpm` | string \| null | Cost of a thousand impressions; null where there is none. |
| `fields.cpe` | string \| null | Cost of one interaction; null where there is none. |
| `fields.cpv` | string \| null | Cost of one read; null where there is none. |
| `fields.shop_visit_cost` | string \| null | Cost per shop visitor a note brings; null where there is none. |
| `fields.median_impressions` | integer \| null | Median impressions of a note. |
| `fields.median_reads` | integer \| null | Median reads of a note. |
| `fields.median_engagements` | integer \| null | Median interactions of a note. |
| `fields.median_shop_visits` | integer \| null | Median shop visitors a note brings. |
| `fields.points` | array \| null | The same figures day by day, oldest first: date, cpm, cpe, cpv, shop_visit_cost and the four medians. |

### `entry:pgy_note`

| 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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `type` | "entry" | The object type. |
| `entry_type` | "pgy_note" | 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` | "image" \| "video" \| null | image for an image note, video for a video note. |
| `fields.text` | string \| null | The note's text. |
| `fields.published_at` | string \| null | When it was published. |
| `fields.images` | string[] \| null | Addresses of its pictures, in order. |
| `fields.creator_id` | string \| null | The creator's marketplace ID, as the other creator calls take it. |
| `fields.creator_name` | string \| null | The creator's name. |
| `fields.brand` | string \| null | The brand it was reported as sponsored by; null when it is no reported sponsored note. |
| `fields.brand_id` | string \| null | The platform account ID of that brand; null when there is none. |
| `fields.impressions` | integer \| null | Impressions. |
| `fields.views` | integer \| null | Reads. |
| `fields.likes` | integer \| null | Likes. |
| `fields.collects` | integer \| null | Saves. |
| `fields.comments` | integer \| null | Comments. |
| `fields.shares` | integer \| null | Shares. |
| `fields.follows` | integer \| null | Followers the note brought its creator. |
| `fields.component_clicks.comment_area` | "normal" \| "high" \| "very_high" \| null | Click band of the brand's comment-area component: normal (0–2%), high (2–10%) or very_high; null when the note has none. |
| `fields.component_clicks.content` | "normal" \| "high" \| "very_high" \| null | Click band of the in-text component; null when the note has none. |
| `fields.component_clicks.note_bottom` | "normal" \| "high" \| "very_high" \| null | Click band of the component at the bottom of the note; null when the note has none. |

### `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `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. |

### `entry:account_owner`

| 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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `type` | "entry" | The object type. |
| `entry_type` | "account_owner" | 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.owner_type` | "company" \| "government" \| "media" \| "individual" \| "other" \| null | What the owner is: company, government, media, individual or other. |
| `fields.registration_id` | string \| null | The number the owner is registered under, such as a unified social credit code; null where the platform gives none. |
| `fields.country` | string \| null | The owner's country or region, in the platform's words. |
| `fields.verification` | "verified" \| "unverified" \| "expired" \| null | The account's verification: verified, unverified or expired. |
| `fields.verification_type` | string \| null | The kind of verification, in the platform's words; null when not verified. |
| `fields.verified_at` | string \| null | When the verification was granted. |
| `fields.account_id` | string \| null | The account you asked about. |
| `fields.account_created_at` | string \| null | When the account was registered. |

### `entry:miniprogram`

| 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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `type` | "entry" | The object type. |
| `entry_type` | "miniprogram" | 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.app_id` | string \| null | The AppID (starting with wx), used to open or link to the mini program; null where the platform gives none. |
| `fields.description` | string \| null | What the mini program says it is. |
| `fields.owner_name` | string \| null | The company or body that runs it. |
| `fields.owner_verified` | boolean \| null | Whether the owner is verified. |
| `fields.recent_users` | integer \| null | How many used it lately, as the platform shows it; a figure shown like 1万+ is a lower bound. |
| `fields.is_game` | boolean \| null | Whether it is a mini game. |

### `entry:follower_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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `type` | "entry" | The object type. |
| `entry_type` | "follower_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` | integer \| null | Net followers gained over those days; negative when followers were lost. |
| `fields.growth` | number \| null | That gain against the followers at the start: 0.01 is 1% more. |
| `fields.points` | array \| null | Followers day by day, oldest first: date, followers. |

### `entry:channels_share_link`

| 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. |
| `extra` | object | What the platform gives of this item beyond the fields below, under the platform's own names (an IP location, a uid, a showcase flag); the interface's extra_fields says what each is. Empty when there is nothing more. Of a comment or a review, never who wrote it. |
| `type` | "entry" | The object type. |
| `entry_type` | "channels_share_link" | 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.share_url` | string \| null | A link that opens the video in WeChat (also the entry's url): a new one each time, and the old ones still open it. |

## Versions and deprecation

- The API's version is in its address (`/v1`) and in every answer (`schema_version: "v1"`).
- Within a version, fields and error codes are only added: ignore the ones your code does not know. A field that is there stays, and a value the platform cannot give is `null`.
- A published MCP tool name or `op` name is never removed or reused. An interface can be paused: the catalog, its page and the answer say so, and a paused call is not charged.
- A change that would break existing calls comes as a new version, announced in the changelog (https://socialtoai.app/changelog/) before the old one stops.

## 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.retry_after_seconds` | integer | With an upstream_error worth one more try: how many seconds to wait before sending it once more. (may be absent) |
| `error.why` | string | With not_found, when the platform says why: deleted, self_only, partial, withheld, no_such, closed or link_refused. (may be absent) |
| `error.platform_says` | string | The platform's own words about it, as it gave them (at most 200 characters). (may be absent) |
| `error.charged` | "true" | true when this failure was charged: a lookup of something not there, where the platform's source charges for it. Absent: nothing was charged. (may be absent) |
| `error.alternative.op` | string | With an upstream_error of a call that has a backup source: the backup call. (may be absent) |
| `error.alternative.credits` | integer | What the backup call costs. (may be absent) |
| `error.alternative.call` | object | The same request on the backup, ready to send. It is never sent unless you send it. (may be absent) |
| `error.alternative.note` | string | One sentence on it, for the AI. (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.mcp_call.tool` | string | The MCP tool to call. (may be absent) |
| `error.fix.mcp_call.arguments` | object | Its arguments. (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 request that fails as a whole 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.app/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.app/docs/api/results.md).
