# Topic

Schemas

Public topic pages from a platform's search, with their title, the platform's summary and the related searches it suggests.

## Endpoints

2 endpoints return topics on Instagram and Pinterest.

- [GETInstagram Topic API`/v1/instagram/topic`](https://socialtap.dev/docs/reference/instagram/topic/index.md)
- [GETPinterest Topic API`/v1/pinterest/topic`](https://socialtap.dev/docs/reference/pinterest/topic/index.md)

## Schema

Every endpoint above returns this object as `data`. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform ID (instagram, tiktok, …). |
| `id` | `string` | Platform-native topic ID; on platforms whose topic pages are keyed by their words (Instagram), the words lowercased and joined by hyphens (harry-potter). |
| `name` | `string` or `null` | The topic's title as its page shows it (Harry Potter); null when the source does not show it. |
| `url` | `string` (uri) | Canonical topic page URL. |
| `description` | `string` or `null` | The platform's summary of the topic, as plain text with paragraph breaks (on Instagram, superscript markers ¹, ² cite platform_specific.instagram.source_urls by position). Null when the page has none. |
| `related_searches` | `string[]` | Related searches the platform suggests for the topic, in its order; each is a topic of its own (pass it as url). \[\] when none. |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `platform_specific.instagram` | `object` or `null` | An Instagram topic's own fields. |
| `platform_specific.instagram.is_category` | `boolean` or `null` | Instagram shows the topic as a category (a broad topic made of narrower ones, without a post count of its own); null when the source cannot tell. |
| `platform_specific.instagram.source_urls` | `string[]` | Web pages the description draws on, in the order its superscript markers number them (¹ is the first); \[\] when it cites none. |
| `platform_specific.instagram.post_count` | `integer` or `null` | Reels Instagram counts under the topic, cut to the digits it shows (46M for 46,656,326; in approximate_fields); null when the page shows none. |
| `platform_specific.pinterest` | `object` or `null` | A Pinterest topic's own fields. |
| `platform_specific.pinterest.search_count` | `integer` or `null` | How many searches Pinterest counts for the topic's words, as its ideas page data states it (Pinterest doesn't say over which period); null when the source does not state it. |
| `platform_specific.pinterest.follower_count` | `integer` or `null` | Accounts following the topic on Pinterest; null for a topic that is no interest accounts can follow (is_interest false). |
| `platform_specific.pinterest.is_category` | `boolean` or `null` | The topic is one of Pinterest's top categories (Travel, Beauty, …), as its ideas page lists them. |
| `platform_specific.pinterest.is_interest` | `boolean` or `null` | The topic is one of Pinterest's interests, which pins are filed under and accounts can follow; false for a page made for a search phrase. |
| `platform_specific.pinterest.updated_at` | `string` (date-time) or `null` | When Pinterest last updated the topic's page data (its counts and related topics). |
| `platform_specific.pinterest.parent_topics` | `object[]` | The broader topics this one sits under, broadest first, as the page's breadcrumbs show them; \[\] for a top category. |
| `platform_specific.pinterest.parent_topics[].id` | `string` | The topic's ID. |
| `platform_specific.pinterest.parent_topics[].name` | `string` or `null` | The topic's name as the page shows it. |
| `platform_specific.pinterest.parent_topics[].url` | `string` (uri) | The topic's ideas page. |
| `platform_specific.pinterest.refinements` | `object[]` | The narrower topics the page offers as buttons above its pins, in its order; \[\] when none. |
| `platform_specific.pinterest.refinements[].label` | `string` or `null` | The button's text (Blue for Blue Star Nail Designs). |
| `platform_specific.pinterest.refinements[].id` | `string` | The narrower topic's ID. |
| `platform_specific.pinterest.refinements[].name` | `string` or `null` | The narrower topic's full name. |
| `platform_specific.pinterest.refinements[].url` | `string` (uri) | The narrower topic's ideas page. |
| `platform_specific.pinterest.related_topics` | `object[]` | Related topics the page links to, in its order; \[\] when none. |
| `platform_specific.pinterest.related_topics[].id` | `string` | The topic's ID. |
| `platform_specific.pinterest.related_topics[].name` | `string` or `null` | The topic's name as the page shows it. |
| `platform_specific.pinterest.related_topics[].url` | `string` (uri) | The topic's ideas page. |
| `platform_specific.pinterest.trending_searches` | `string[]` | Searches Pinterest shows as trending for the topic, in its order; \[\] when none. |
| `platform_specific.pinterest.related_boards` | `object[]` | Boards Pinterest shows on the topic's page, in its order; \[\] when none. |
| `platform_specific.pinterest.related_boards[].id` | `string` or `null` | The board's ID. |
| `platform_specific.pinterest.related_boards[].title` | `string` or `null` | The board's name. |
| `platform_specific.pinterest.related_boards[].url` | `string` (uri) or `null` | The board's link. |
| `platform_specific.pinterest.cover_image_url` | `string` (uri) or `null` | The picture Pinterest shows for the topic when its page is shared (one of its pins' pictures, so it changes over time); null when the page has none. |
| `approximate_fields` | `string[]` | JSON paths of values rounded by the platform or parsed from display text ("189M reels": platform_specific.instagram.post_count). \[\] when all exact. |
| `unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. \[\] when every list is known. |

## Item errors

Besides the [request-level errors](https://socialtap.dev/docs/errors/index.md) every endpoint can return, topic endpoints return:

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `not_found` | 404 | No | The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). | Check the link or ID. Do not retry. |

---

[HTML version](https://socialtap.dev/resources/topic/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)