--- title: "List mentions" method: GET path: "/topics/{topicId}/mentions" tags: ["Mentions"] --- # List mentions `GET /topics/{topicId}/mentions` ## Request - Base URL: `https://api.youscan.io/api/external` - URL: `https://api.youscan.io/api/external/topics/{topicId}/mentions` - Auth: one of: - API key in header `X-API-KEY` - API key in query parameter `apiKey` - TypeScript: (a function with typed inputs; its response is checked against the schema) Use this action to retrieve mentions matching criteria. This endpoint is rate limited: no more than 10 requests per 10 seconds and no more than 5 concurrent requests per user. Requests beyond those limits are rejected with a 429 status code. ## Path parameters - `topicId` integer, required ## Query parameters - `from` string - `to` string - `addedFrom` string - `addedTo` string - `sinceSeq` integer - `sentiment` string[] - `excludeSentiment` string[] - `engagementFrom` integer - `engagementTo` integer - `engagementCollectedFrom` string - `engagementCollectedTo` string - `sources` string[] - `excludeSources` string[] - `sourceTypes` SourceTypeFilter[] - `excludeSourceTypes` SourceTypeFilter[] - `postTypes` PostType[] - `excludePostTypes` PostType[] - `tags` string[] - `excludeTags` string[] - `autoCategories` string[] - `excludeAutoCategories` string[] - `starred` boolean - `tagged` boolean - `processed` boolean - `deleted` boolean - `spam` boolean - `textQuery` string - `dedup` boolean - `htmlSanitize` boolean - `timeZone` string - `size` integer - `skip` integer - `orderBy` 'published' | 'publishedAsc' | 'seqAsc' | 'engagement' ## Response `200` Mentions matching criteria. - object - `total` integer: Total number of mentions matching criteria. - `lastSeq` integer: The highest mention sequence number in the whole topic — not of this page, so don't use it as the `sinceSeq` paging cursor. - `mentions` Mention[] - `id` string: Mention identifier that can be used to label a particular mention. - `seq` integer: Mention sequence number. Useful for paging, when the `sinceSeq` filter and `seqAsc` sort order are used. - `published` string, date-time: Date and time when the mention was published, in ISO 8601 format. - `addedAt` string, date-time: Date and time when the mention was saved to the topic. - `url` string, nullable: Mention URL. - `title` string, nullable: Mention's title. For example, for a comment it may contain the parent post's snippet. - `text` string, nullable: Snippet of the mention content. - `fullText` string, nullable: Full text of the mention. - `imageUrl` string, nullable: Image URL. - `images` string[], nullable: Array of image URLs. - `source` string: Mention's source (domain). - `author` MentionProfile - `profileId` string, nullable: Profile ID in the source system. - `url` string, nullable: Link to the profile. - `name` string, nullable: Display name. - `nickname` string, nullable: Username/handle. - `bio` string, nullable: Profile description. Available for authors only. - `avatarUrl` string, nullable: URL to the avatar image. - `subscribers` integer, nullable: Number of friends and/or followers. - `gender` 'unknown' | 'community' | 'male' | 'female' - `age` integer, nullable: Author age. Available for authors only. - `jobs` string[], nullable: Author job categories. Requires the Audience Insights addon. - `interests` string[], nullable: Author interests. Requires the Audience Insights addon. - `interestCategories` string[], nullable: Author interest categories. Requires the Audience Insights addon. - `publicationPlace` MentionProfile - `profileId` string, nullable: Profile ID in the source system. - `url` string, nullable: Link to the profile. - `name` string, nullable: Display name. - `nickname` string, nullable: Username/handle. - `bio` string, nullable: Profile description. Available for authors only. - `avatarUrl` string, nullable: URL to the avatar image. - `subscribers` integer, nullable: Number of friends and/or followers. - `gender` 'unknown' | 'community' | 'male' | 'female' - `age` integer, nullable: Author age. Available for authors only. - `jobs` string[], nullable: Author job categories. Requires the Audience Insights addon. - `interests` string[], nullable: Author interests. Requires the Audience Insights addon. - `interestCategories` string[], nullable: Author interest categories. Requires the Audience Insights addon. - `sentiment` 'positive' | 'neutral' | 'negative' | 'undefined' - `sourceType` 'social' | 'blog' | 'forum' | 'messenger' | 'news' | 'reviews' | 'other' - `resourceType` string, nullable: Duplicate of `sourceType`. Use `sourceType` instead. - `language` string, nullable: 3-letter ISO 639 language code. - `imageActivities` string[], nullable: Activities detected on the image. Available for customers with the Visual Insights option enabled. - `imageBrands` string[], nullable: Brands detected on the image. Available for customers with the Visual Insights option enabled. - `imageColors` string[], nullable: HEX color codes detected on the image. Available for customers with the Visual Insights option enabled. - `imageObjects` string[], nullable: Objects detected on the image. Available for customers with the Visual Insights option enabled. - `imagePeople` string[], nullable: People detected on the image. Available for customers with the Visual Insights option enabled. - `imageScenes` string[], nullable: Scenes detected on the image. Available for customers with the Visual Insights option enabled. - `imageTexts` string[], nullable: Texts detected on the image via OCR. Available for customers with the Visual Insights option enabled. - `postType` 'post' | 'repost' | 'extendedRepost' | 'comment' - `contentTypes` string[], nullable: Content types. - `collectionMethods` string[], nullable: How the mention was matched into the topic: `text` by the text query, `ocrText` by text recognised on an image, `imageLogo` by a detected logo, `imageFeature` by other image attributes, `audio` by a transcript, `channel` by an owned page, `manual` when added by hand, `import` when uploaded. A mention can match through several methods at once. - `sourceFormat` 'instagramReels' | 'instagramStories' | 'pinterestStoryPins' | 'youTubeShorts' | 'facebookReels' | 'facebookStories' | 'tikTokPhoto' | 'twitterNote' | 'youTubeLive' | 'facebookLive' | 'twitchLive' | 'twitterCommunityNote': Source-specific format of the post. - `tags` string[]: List of tags applied to the mention. - `rating` number, nullable: Rating in the 0..5 range. Usually available for reviews. - `autoCategories` string[], nullable: List of detected [auto-categories](https://youscan.io/2018/04/wom-autocategory/). - `subjects` string[], nullable: List of Subjects detected in the mention. - `starred` boolean: Whether the mention is starred. - `processed` boolean: Whether the mention has been processed. - `engagement` MentionEngagement - `likes` integer, nullable - `dislikes` integer, nullable - `comments` integer, nullable - `reposts` integer, nullable - `views` integer, nullable - `reach` integer, nullable - `saves` integer, nullable - `impressions` integer, nullable - `engagement` integer, nullable: Sum of likes, dislikes, comments and reposts. - `reactions` Reactions - `total` integer: Total number of reactions. - `angry` integer, nullable - `haha` integer, nullable - `love` integer, nullable - `sad` integer, nullable - `wow` integer, nullable - `care` integer, nullable - `dateCollected` string, date-time, nullable: When the engagement data was last collected. - `postId` string, nullable: Mention ID in the external API. Be aware, it's not the YouScan ID, but the ID received from a 3rd party API. Its uniqueness only makes sense within the particular source. For example, a mention from Instagram could have the same postId as some mention from Facebook. - `parentPostId` string, nullable: Direct parent of the mention. E.g. for a comment, it would be the parent post ID. For reposts, parentPostId is the postId of the original post. - `discussionId` string, nullable: You may use this field to group mentions into a discussion, e.g. a post with all comments and replies. - `country` string, nullable: ISO alpha-2 country code. - `region` string, nullable - `city` string, nullable - `note` string, nullable: Internal note added in YouScan. - `aspects` string[], nullable: List of Aspects detected in the mention. - `sentimentAspects` object[], nullable: List of aspects with their sentiment. - `aspect` string - `sentiment` 'positive' | 'neutral' | 'negative' | 'undefined' - `potentialReach` integer, nullable: Potential reach. - `authorJobs` string[], nullable: List of author job categories. Requires the Audience Insights addon. - `authorInterests` string[], nullable: List of author interests. Requires the Audience Insights addon. - `authorInterestCategories` string[], nullable: List of author interest categories. Requires the Audience Insights addon. - `customTags` string[], nullable: List of custom tags. - `categories` Category[]: List of assigned categories grouped with assigned subcategories. - `id` integer: Category ID. - `name` string: Category name. - `subCategories` SubCategory[]: Configured (or, in mention responses, assigned) subcategories. - `id` integer: Subcategory ID. - `name` string: Subcategory name. - `speechContent` MentionSpeechContent - `language` string: ISO 639-3 code of the spoken language, detected from the transcript. - `segments` MentionSpeechContentSegment[]: The transcript split into timed segments, in playback order. - `text` string: Segment text. Parts matching the topic query are wrapped in `` tags. - `startTime` integer: Segment start offset from the start of the track, in milliseconds. - `endTime` integer: Segment end offset from the start of the track, in milliseconds. - `hasMatches` boolean: Whether this segment contains a topic query match. - `timecodeUrlTemplate` string, nullable: Template for deep-linking into the source video at a given segment. The `{t}` placeholder stands for a segment's `startTime` converted to whole seconds, so `https://www.youtube.com/watch?v=abc&t={t}s` becomes `https://www.youtube.com/watch?v=abc&t=65s` for a segment starting at 65432 ms. Sent once per mention rather than once per segment, because the only part that varies between segments is the timecode, which `startTime` already carries. Omitted when the source has no timecode deep links (today only `youtube.com` does). ## Other responses - `400`: The request is invalid. - `401`: The API key is missing or invalid. - `404`: Topic not found or you don't have access to it. - `429`: Rate limit exceeded (10 requests per 10 seconds, 5 concurrent requests). --- [API](https://skmtc.dev/youscan/apis/youscan-api.md) - [All operations](https://skmtc.dev/youscan/apis/youscan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/youscan/apis/youscan-api/revisions/f5bef260f153?raw)