--- title: "Get mentions by IDs (POST)" method: POST path: "/topics/{topicId}/get-mentions" tags: ["Mentions"] --- # Get mentions by IDs (POST) `POST /topics/{topicId}/get-mentions` ## Request - Base URL: `https://api.youscan.io/api/external` - URL: `https://api.youscan.io/api/external/topics/{topicId}/get-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) Same as the GET variant, but accepts the IDs in the request body — useful when the list of IDs is too long for a URL. Maximum 500 IDs per request. ## Path parameters - `topicId` integer, required ## Request body - object - `ids` integer[], required - `timeZone` string: IANA time zone identifier used to convert mention dates in the response. Defaults to the API key owner's time zone. ## Response `200` Requested mentions. - object - `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. --- [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)