Mentions

Mentions answer: which posts carried the attention, who amplified them, and how good was that attention?

Endpoint	Returns
`GET /v2/data/top-mentions`	The most significant mentions of a ticker, ranked by engagement
`GET /v2/data/keyword-mentions`	Mentions matching up to five keywords or an account, with the author's username
`GET /v2/data/token-news`	Token news posts from X accounts tagged as news sources

All three return links and engagement metrics. They do not return tweet text and do not return sentiment. To read a post, follow its link with the X API, or use the SDK's fetchRawTweets: true option with an X bearer token.

Top Mentions

GET /v2/data/top-mentions: the most significant mentions of a ticker in a time window, ranked by engagement (viewCount, then mentionedAt, then relevance).

{
  "success": true,
  "data": [
    {
      "tweetId": "2045186844212756697",
      "link": "https://x.com/BillyM2k/status/2045186844212756697",
      "likeCount": 465,
      "repostCount": 45,
      "viewCount": 15914,
      "quoteCount": 10,
      "replyCount": 62,
      "bookmarkCount": 12,
      "mentionedAt": "2026-04-17T17:05:16+00:00",
      "type": "post",
      "repostBreakdown": { "smart": 0, "ct": 0 }
    }
  ],
  "metadata": { "total": 52, "page": 1, "pageSize": 2 }
}

curl -H "x-elfa-api-key: $ELFA_API_KEY" \
  "https://api.elfa.ai/v2/data/top-mentions?ticker=DOGE&timeWindow=24h&pageSize=2"

Field	Type	Meaning
`data[].tweetId`	string	Post ID. A string, to keep 64-bit IDs precise
`data[].link`	string	URL of the source post
`data[].likeCount`, `repostCount`, `viewCount`, `quoteCount`, `replyCount`, `bookmarkCount`	number or null	Engagement counts
`data[].mentionedAt`	string	ISO 8601 timestamp. Not a unix timestamp
`data[].type`	string	`post`, `repost`, `quote`, `reply`, `note` or `article`
`data[].repostBreakdown.smart`	number	Reposts by smart accounts
`data[].repostBreakdown.ct`	number	Reposts by crypto-Twitter accounts
`metadata.total`, `page`, `pageSize`	number	Pagination state

Parameter	Required	Type	Meaning
`ticker`	Yes	string	Ticker to get mentions for. With a `$` prefix (`$SOL`, URL-encoded `%24SOL`), only exact cashtags match. Without it, results include cashtags and general token references
`timeWindow`	No	string	Window such as `1h`, `24h`, `7d`. Default `1h`
`from`	No	number	Start, unix timestamp
`to`	No	number	End, unix timestamp
`page`	No	number	Page number. Default `1`
`pageSize`	No	number	Items per page. Default `10`
`reposts`	No	boolean	Not described in the spec

Response Shape

The envelope is { success, data, metadata }. data is a flat array of mentions. Pagination state lives in metadata (total, page, pageSize), never in the top level.

No Account Object

Unlike keyword mentions, top mentions does not return an account object per mention. To get the author, use keyword mentions.

Reading the Metrics

Compare repostBreakdown.smart with repostBreakdown.ct to separate smart amplification from broad amplification.
A high bookmarkCount relative to likeCount can indicate stronger intent than a like.
A high quoteCount relative to repostCount suggests people are arguing, not just passing it along.
Use link when a report, alert or agent answer needs a source.

Also via x402: GET /x402/v2/data/top-mentions

Keyword Mentions

GET /v2/data/keyword-mentions: mentions matching keywords, an account, or both, within a time window.

{
  "success": true,
  "data": [
    {
      "tweetId": "2045519677062066348",
      "link": "https://x.com/BillyM2k/status/2045519677062066348",
      "likeCount": 0,
      "repostCount": 0,
      "viewCount": 0,
      "quoteCount": 0,
      "replyCount": 0,
      "bookmarkCount": 0,
      "mentionedAt": "2026-04-18T15:07:49+00:00",
      "type": "post",
      "account": { "username": "BillyM2k", "isVerified": false },
      "repostBreakdown": { "smart": 0, "ct": 0 }
    }
  ],
  "metadata": { "total": 1, "cursor": 1776524869000 }
}

curl -H "x-elfa-api-key: $ELFA_API_KEY" \
  "https://api.elfa.ai/v2/data/keyword-mentions?accountName=BillyM2k&timeWindow=7d"

Field	Type	Meaning
`data[]`		Same mention fields as top mentions, plus `account`
`data[].account.username`	string	Author's X username
`data[].account.isVerified`	boolean	Whether the author is verified
`metadata.cursor`	number	Millisecond timestamp. Pass it back as `cursor` for the next page
`metadata.total`	number	Size of the full matching result set. May be capped at 10000

Parameter	Required	Type	Meaning
`keywords`	One of `keywords`, `accountName`	string	Up to 5 keywords, comma-separated
`accountName`	One of `keywords`, `accountName`	string	Account username to filter by
`timeWindow`	No	string	Window such as `24h`, `7d`. Default `7d`
`from`	No	number	Start, unix timestamp
`to`	No	number	End, unix timestamp
`limit`	No	number	Results per call. Default `20`, max `30`
`searchType`	No	string	`and` (all terms must match) or `or` (any term matches)
`cursor`	No	string	`metadata.cursor` from the previous response
`reposts`	No	boolean	Not described in the spec

Keywords or Account Required

Send keywords, accountName, or both. A request with neither is refused.

Cursor Pagination

Unlike top mentions, which uses page and pageSize, this endpoint is cursor-paginated. Pass metadata.cursor back as the cursor query parameter. Page until data is empty; metadata.cursor is omitted only on that empty page. metadata.total is the complete matching result set, not the remainder after the cursor.

Minimal Account Object

Each mention carries an account object with only username and isVerified. No ID, display name, follower count or bio is returned. account may be omitted when the underlying record has no account name.

Field Notes

mentionedAt is an ISO 8601 string, not a unix timestamp. repostBreakdown.smart counts reposts by smart accounts; repostBreakdown.ct counts reposts by crypto-Twitter accounts. This is the mention endpoint that returns the author, so account.username is the join key for Smart Stats.

Also via x402: GET /x402/v2/data/keyword-mentions

Token News

GET /v2/data/token-news: token-related news mentions, as mention objects with links and engagement metrics.

{
  "success": true,
  "data": [
    {
      "tweetId": "string",
      "link": "string",
      "likeCount": 1,
      "repostCount": 1,
      "viewCount": 1,
      "quoteCount": 1,
      "replyCount": 1,
      "bookmarkCount": 1,
      "mentionedAt": "string",
      "type": "repost",
      "repostBreakdown": { "ct": 1, "smart": 1 }
    }
  ],
  "metadata": { "pageSize": 1, "page": 1, "total": 1 }
}

curl -H "x-elfa-api-key: $ELFA_API_KEY" \
  "https://api.elfa.ai/v2/data/token-news?coinIds=bitcoin&timeWindow=7d&pageSize=1"

The spec's example uses placeholder values.

Field	Type	Meaning
`data[]`		Same mention fields as top mentions. No `account` object
`metadata.total`, `page`, `pageSize`	number	Pagination state

Parameter	Required	Type	Meaning
`coinIds`	No	string	CoinGecko coin IDs to filter by, comma-separated
`timeWindow`	No	string	Window such as `24h`, `7d`. Default `7d`
`from`	No	number	Start, unix timestamp
`to`	No	number	End, unix timestamp
`page`	No	number	Page number. Default `1`
`pageSize`	No	number	Items per page. Default `20`
`reposts`	No	boolean	Not described in the spec

News Means X Posts

Results are X posts from accounts tagged as news sources, not articles published by news outlets. Expect posts, with the reach and engagement metrics that come with them.

Evidence, Not Explanation

Token news returns source links and metrics, not prose. Use it to check whether a move has news behind it before acting, and to cite real news posts before summarizing. For a written summary of a window, use event summary.

Also via x402: GET /x402/v2/data/token-news

Errors

These endpoints use the shared v2 errors: see Enums and Errors. Keyword mentions refuses a request with neither keywords nor accountName.

Reference: top-mentions, keyword-mentions, token-news
Next: Accounts for the stats of a mention's author
Agent Playbooks for endpoint chains

Top Mentions​

Response Shape​

No Account Object​

Reading the Metrics​

Keyword Mentions​

Keywords or Account Required​

Cursor Pagination​

Minimal Account Object​

Field Notes​

Token News​

News Means X Posts​

Evidence, Not Explanation​

Errors​

Related​