Endpoints
2 endpoints return topics on Instagram and Pinterest.
Schema
Every endpoint above returns this object as data. The standard meta comes with every response.
platformstringPlatform ID (instagram, tiktok, …).
idstringPlatform-native topic ID; on platforms whose topic pages are keyed by their words (Instagram), the words lowercased and joined by hyphens (harry-potter).
namestringnullableThe topic's title as its page shows it (Harry Potter); null when the source does not show it.
urlstring uriCanonical topic page URL.
descriptionstringnullableThe 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_searchesstring[]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_specificobjectFields only this platform has, under its ID (platform_specific.<platform>); each null when unknown.
ShowHide 2 child fields
instagramobjectnullableAn Instagram topic's own fields.
ShowHide 3 child fields
is_categorybooleannullableInstagram 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.
source_urlsstring[]Web pages the description draws on, in the order its superscript markers number them (¹ is the first); [] when it cites none.
post_countintegernullableReels 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.
pinterestobjectnullableA Pinterest topic's own fields.
ShowHide 11 child fields
search_countintegernullableHow 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.
follower_countintegernullableAccounts following the topic on Pinterest; null for a topic that is no interest accounts can follow (is_interest false).
is_categorybooleannullableThe topic is one of Pinterest's top categories (Travel, Beauty, …), as its ideas page lists them.
is_interestbooleannullableThe 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.
updated_atstring date-timenullableWhen Pinterest last updated the topic's page data (its counts and related topics).
parent_topicsobject[]The broader topics this one sits under, broadest first, as the page's breadcrumbs show them; [] for a top category.
ShowHide 3 child fields
idstringThe topic's ID.
namestringnullableThe topic's name as the page shows it.
urlstring uriThe topic's ideas page.
refinementsobject[]The narrower topics the page offers as buttons above its pins, in its order; [] when none.
ShowHide 4 child fields
labelstringnullableThe button's text (Blue for Blue Star Nail Designs).
idstringThe narrower topic's ID.
namestringnullableThe narrower topic's full name.
urlstring uriThe narrower topic's ideas page.
related_topicsobject[]Related topics the page links to, in its order; [] when none.
ShowHide 3 child fields
idstringThe topic's ID.
namestringnullableThe topic's name as the page shows it.
urlstring uriThe topic's ideas page.
trending_searchesstring[]Searches Pinterest shows as trending for the topic, in its order; [] when none.
related_boardsobject[]Boards Pinterest shows on the topic's page, in its order; [] when none.
ShowHide 3 child fields
idstringnullableThe board's ID.
titlestringnullableThe board's name.
urlstring urinullableThe board's link.
cover_image_urlstring urinullableThe 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_fieldsstring[]JSON paths of values rounded by the platform or parsed from display text ("189M reels": platform_specific.instagram.post_count). [] when all exact.
unknown_fieldsstring[]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 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. |