Scroll by Keyword

POST/v2/organizations/{organizationId}/keywords/{keywordId}/mentions/scroll

Returns a paginated list of mentions for a specific keyword. Use this endpoint to retrieve and page through mentions scoped to a single keyword rather than the entire organization.

100 req/60s

Parameters

Path Parameters

organizationIdinteger (int64)requiredpath

The unique identifier of the organization.

keywordIdinteger (int32)requiredpath

The unique identifier of the keyword to scroll mentions for.

Request Body

The request body is a ScrollRequest containing a query, pagination settings, and optional flags:

Field	Type	Description
query	object	A FeedsSearchQueryRequest defining the search criteria (see below).
paged	object	Pagination and sorting settings.
paged.count	integer (int32)	Number of mentions to return per page.
paged.sorted	object	Sorting configuration with direction (ASC or DESC) and property (sort field).
scrollToken	string	Token from a previous response to fetch the next page of results. Omit on the first request.

Sort Properties

PUBLISHED_TIME, FEED_TIME, REACH, VIRALITY, INTERACTIONS, INFLUENCE, ENGAGEMENT

Query Object (FeedsSearchQueryRequest)

Field	Type	Description
query.feeds	array	Array of feed objects with groupId (int64) and keywordId (int64) to scope the search. Optional -- omit to search all feeds.
query.feedTime	object	Time range filter based on when the mention entered the feed. Use relative (enum) for preset ranges, or from/to (ISO datetime) for custom ranges.
query.publishedTime	object	Time range filter based on when the mention was published. Same structure as feedTime.
query.mentionFilter	object	Filter criteria for narrowing mentions.

Relative Time Period Values

TODAY, YESTERDAY, LAST_24_HOURS, LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, THIS_MONTH, THIS_WEEK, LAST_WEEK, LAST_MONTH

Mention Filters

Each filter field uses a FilterClause pattern with optional any, all, must, and not sub-fields:

Filter Field	Type	Description
mentionType	FilterClause	Filter by source type. Values: WEB, FACEBOOK, TWITTER, FORUM, COMMENT, YOUTUBE, INSTAGRAM, REDDIT, TIKTOK, PRINT, RADIO, TV, BLUESKY
sentiment	FilterClause	Filter by sentiment. Values: POSITIVE, NEUTRAL, NEGATIVE, UNDEFINED

Try it

Parameters

organizationId *integer

Organization ID

keywordId *integer

Keyword ID

Time Range

Time Range

Period enumSelect...TodayYesterdayLast 24 hoursLast 7 daysLast 30 daysLast 90 daysThis monthThis weekLast weekLast month

From date

To date

Filters

Source Types select multiple

Filter by source type

Sentiment select multiple

Filter by sentiment

Pagination

Page Size integer

Mentions per page

Sort Direction enumSelect...Newest firstOldest first

Sort By enumSelect...Published timeFeed timeReachViralityInteractionsInfluenceEngagement

Scroll Token string

For next page

Response

{
  "mentions": [
    {
      "id": 987654321,
      "type": "WEB",
      "title": "Tesla announces new factory",
      "mention": "Tesla has announced plans to build a new factory...",
      "url": "https://example.com/article/tesla-factory",
      "author": "TechNews",
      "reach": 50000,
      "virality": 0.85,
      "interaction": 1200,
      "influenceScore": 78,
      "autoSentiment": "POSITIVE",
      "languages": ["en"],
      "locations": ["US"],
      "insertTime": 1705312800000,
      "keywords": ["Tesla"]
    }
  ],
  "scrollToken": "eyJzZWFyY2hBZnRlciI6..."
}

Response Fields

Field	Type	Description
mentions	array	List of mention objects matching the query for this keyword.
scrollToken	string	Opaque token to pass in the next request to retrieve the following page of results.

Mention Object

Field	Type	Description
id	integer (int64)	Unique identifier for the mention
type	string	Source type (e.g. WEB, TWITTER, FACEBOOK, YOUTUBE)
title	string	Title of the mention, if available
mention	string	Text snippet of the mention content
url	string	URL where the original mention can be found
author	string	Name or handle of the mention author
influencer	string	Influencer associated with the mention, if any
reach	integer (int32)	Estimated audience reach
virality	number (double)	Virality score of the mention
interaction	integer (int64)	Total number of interactions (likes, shares, comments, etc.)
influenceScore	integer (int64)	Influence score of the source
autoSentiment	string	Automatically detected sentiment (POSITIVE, NEUTRAL, NEGATIVE, UNDEFINED)
languages	array of string	Detected languages of the mention
locations	array of string	Detected geographic locations
insertTime	integer (int64)	Unix timestamp (milliseconds) when the mention was ingested
databaseInsertTime	integer (int64)	Unix timestamp (milliseconds) when the mention was stored in the database
image	string	URL of an associated image, if available
keywords	array of string	Keywords that matched this mention

Pagination

The scroll endpoint uses token-based pagination for efficient retrieval of large result sets.

1. First request -- Send your query without a scrollToken. The response includes the first page of results and a scrollToken.

2. Subsequent requests -- Include the scrollToken from the previous response in your next request body. The server returns the next page of results along with a new scrollToken.

3. End of results -- When there are no more results, the scrollToken will be absent or null in the response.

TIP

Always pass the same query and paged parameters across paginated requests. Only add or update the scrollToken field.