Narratives

Narrative endpoints answer why: they attach a written summary or theme, with source links, to a market move.

Endpoint	Returns
GET /v2/data/event-summary	Written event summaries for keyword mentions in a window, with source links. 5 credits.
GET /v2/data/trending-narratives	Written trending narratives from Twitter mentions, with source links. 5 credits.

Event Summary

GET /v2/data/event-summary generates event summaries from keyword mentions within a time period. It costs 5 credits per request, or 1 when it returns 503.

Sample response (from the spec example):

{
  "success": true,
  "data": [
    { "tweetIds": ["string"], "sourceLinks": ["string"], "summary": "string" }
  ]
}

Request:

curl "https://api.elfa.ai/v2/data/event-summary?keywords=bitcoin,etf&timeWindow=24h&searchType=or" \
  -H "x-elfa-api-key: $ELFA_API_KEY"

Field	Type	Meaning
data[].summary	string	Written summary of one event.
data[].sourceLinks	string[]	Links to the posts behind the summary.
data[].tweetIds	string[]	IDs of the posts behind the summary.

Parameter	Required	Type	Meaning
keywords	Yes	string	Keywords to search for, separated by commas.
timeWindow	No	string	Window ending now, e.g. 30m, 1h, 4h, 24h, 7d, 30d. Default 7d.
from	No	number	Start of the window, unix timestamp.
to	No	number	End of the window, unix timestamp.
searchType	No	string	How keywords combine: and or or. Default or.

Cost

5 credits per request. It replaces an ingest, dedupe, clustering and summarization pipeline you would otherwise run.

Uses

• Learn what happened in a window without reading every post.
• Fill a digest, alert or client note; source links travel with each summary.

Also via x402: GET /x402/v2/data/event-summary

Trending Narratives

GET /v2/data/trending-narratives returns trending narratives based on analysis of Twitter mentions. It costs 5 credits per request.

Sample response (from the spec example):

{
  "success": true,
  "data": {
    "metadata": { "error": "string", "total_tweets": 1, "total_narratives": 1 },
    "trending_narratives": [
      { "tweet_ids": ["string"], "source_links": ["string"], "narrative": "string" }
    ]
  }
}

Request:

curl "https://api.elfa.ai/v2/data/trending-narratives?timeFrame=day&maxNarratives=1&maxTweetsPerNarrative=1" \
  -H "x-elfa-api-key: $ELFA_API_KEY"

Field	Type	Meaning
data.trending_narratives[].narrative	string	Written narrative.
data.trending_narratives[].source_links	string[]	Links to the posts behind the narrative.
data.trending_narratives[].tweet_ids	string[]	IDs of the posts behind the narrative.
data.metadata.total_narratives	number	Narratives returned.
data.metadata.total_tweets	number	Not described in the spec.
data.metadata.error	string	Not described in the spec.

Parameter	Required	Type	Meaning
timeFrame	No	string	day or week. Default day.
maxNarratives	No	number	Maximum narratives to return, 1 to 20. Default 7.
maxTweetsPerNarrative	No	number	Maximum posts per narrative, 1 to 20. Default 5.

Cost and Access

5 credits per request. With an API key it requires Grow and above or PAYG. It is also available through x402 pay-per-request.

Uses

• See the theme one level above individual tokens. Narratives often move before the tokens inside them.
• Condition an agent on the prevailing market story instead of one strategy for every market.

Also via x402: GET /x402/v2/data/trending-narratives

Choosing Between Them

Need	Endpoint
Evidence that news exists for a token move	Token news
A source-backed summary for a keyword window	Event summary
The themes currently winning market attention	Trending narratives
A feed of events as they happen, threaded into storylines	API v3 Events

Errors

Status	Endpoint	What it means	What to do
503	Event summary	The matched posts could not be processed into summaries. Not an empty result: a quiet window is a 200 with an empty data. Costs 1 credit, not 5	Retry, or narrow the keywords or the time window
503	Trending narratives	Trending narratives are temporarily unavailable. Not an empty result. Not declared in the spec, so a generated client has no branch for it	Retry with backoff

For every other status, see Enums and Errors.

Related

• Reference: Event summary, Trending narratives
• Next: Accounts, or API v3 Events for the v3 successor to event feeds.