The Narratives endpoint allows you to fetch clusters of related content that Constellation has grouped into coherent narratives. Each narrative includes an AI-generated summary, a description, and an assessment of the claim.
Constellation
An API for understanding online narratives, the posts that make them, and the actors who shape them
The Constellation API provides endpoints that let you analyze social posts, the accounts behind them, and the narratives connecting them. Using advanced AI, the API organizes raw social data into structured insights—showing what is being said, who is amplifying it, how it is propagating across platforms, and what potential risks it may pose to your organization.
The Posts endpoint returns post-level content such as text, author information, engagement metadata, and AI-generated enrichments including risk metrics and narrative identifiers. The Authors endpoint provides account-level context, including cohort membership and other actor-intelligence indicators. The Narratives endpoint returns clusters of related content, an AI-generated assessment of potential risk, a narrative summary, and a description of the narrative itself.
This API is ideal for customers who want to embed Constellation enrichments directly into their own products, dashboards, or analytical workflows.
All boolean and query searches are beta. They are intended to mirror a subset of the ElasticSearch DSL spec, but the current implementation is just an approximate. Any change to the functionality which makes it more-correctly implement that spec is considered non-breaking
Download OpenAPI description
Languages
Servers
https://api-prd.infra-prod.blackbird.ai/v1/
Bodyapplication/jsonrequired
Query, sort, and pagination criteria.
Cursor-Based Pagination:
- For the first page, omit the
afterfield or set it tonull - Use the
endCursorvalue from the previous response'spageInfoas theaftervalue for the next page - The cursor is an identifier to the last row in the previous page
- Example cursor:
eyJjcmVhdGVkQXQiOiIyMDI1LTA4LTI3VDIwOjQ4OjI4LjAwMFoiLCJwb3N0SWQiOiIxOTYwODA2NjQyMjE3NTc0NTAyIn0=
Pagination Flow:
- First request:
{ "query": {...}, "page": { "first": 50 } } - Response includes:
pageInfo.endCursor - Next request:
{ "query": {...}, "page": { "first": 50, "after": "<endCursor from previous>" } }
Any of:
- object
- object
- object
- object
- object
- object
- object
- object
A lucene query to filter on post criteria. Provides the same intent as query, but more text-friendly way of specifying the filter. If both boolean and query are provided, they are combined with a logical AND.
- https://api-prd.infra-prod.blackbird.ai/v1/narratives/-/search
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://api-prd.infra-prod.blackbird.ai/v1/narratives/-/search?projectId=string' \
-H 'Content-Type: application/json' \
-d '{
"boolean": "platform:twitter OR platform:reddit",
"query": {
"bool": {
"must": [
{
"match_phrase": {
"narrative.title": {
"query": "Iranian"
}
}
},
{
"range": {
"narrative.weightedRiskScore": {
"gte": 54
}
}
}
]
}
},
"sort": [
{
"field": "narrative.weightedRiskScore",
"direction": "DESC"
}
],
"page": {
"first": 50
}
}'Bodyapplication/json
Example: [{"compassHeadline":"The expulsion of Iran's ambassador was based on credible security concerns, but the claim's language includes subjective interpretation.","compassLabel":"Caution","compassOneSentence":"The expulsion of Iran's ambassador was based on credible security concerns, but the claim's language includes subjective interpretation.","compassSummary":"The expulsion of Iran's ambassador was based on credible security concerns, but the claim's language includes subjective interpretation.","executiveBriefing":"The expulsion of the Iranian ambassador by Australia has led to significant online discourse, with users expressing mixed feelings about the timing and necessity of the action. Prominent voices criticized the delay in addressing threats from the Iranian regime, particularly following antisemitic incidents. The conversation was largely driven by right-wing users advocating for stronger measures against Iranian influence.","postCount":398,"title":"The expulsion of the Iranian ambassador is seen as a delayed but necessary response to long-known threats from the Iranian regime.","totalEngagement":7713,"narrativeId":"107"}]
Search across all author text fields - author.username, author.displayName, author.profileBio, author.bioLocation. NOTE - Not actually returned as a field in the response, but documented here to facilitate describing the filterability.
Search across all narrative text fields - narrative.title, narrative.compassHeadline, narrative.compassSummary, narrative.compassOneSentence, narrative.executiveBriefing. NOTE - Not actually returned as a field in the response, but documented here to facilitate describing the filterability.
Search across all post text content fields - title, body. NOTE - Not actually returned as a field in the response, but documented here to facilitate describing the filterability.
Compass-generated headline for the narrative.
Example: "The expulsion of Iran's ambassador was based on credible security concerns, but the claim's language includes subjective interpretation."
Compass-generated one-sentence summary.
Example: "The expulsion of Iran's ambassador was based on credible security concerns, but the claim's language includes subjective interpretation."
Compass-generated summary of the narrative.
Example: "The expulsion of Iran's ambassador was based on credible security concerns, but the claim's language includes subjective interpretation."
Executive briefing text for the narrative.
Example: "The expulsion of the Iranian ambassador by Australia has led to significant online discourse, with users expressing mixed feelings about the timing and necessity of the action. Prominent voices criticized the delay in addressing threats from the Iranian regime, particularly following antisemitic incidents. The conversation was largely driven by right-wing users advocating for stronger measures against Iranian influence."
Title of the narrative the post belongs to.
Example: "The expulsion of the Iranian ambassador is seen as a delayed but necessary response to long-known threats from the Iranian regime."
Total engagement across all posts in the narrative.
Example: 7713
Example: {"hasNextPage":true,"endCursor":"eyJjcmVhdGVkQXQiOiIyMDI1LTA4LTI3VDAxOjAwOjEyLjAwMFoiLCJwb3N0SWQiOiIxOTYwNTA3NjA3Njg2MjA1ODc5In0=","sortKey":"created_at DESC, post_id ASC"}
Response
application/json
{ "narratives": [ { … } ], "pageInfo": { "hasNextPage": true, "endCursor": "eyJjcmVhdGVkQXQiOiIyMDI1LTA4LTI3VDAxOjAwOjEyLjAwMFoiLCJwb3N0SWQiOiIxOTYwNTA3NjA3Njg2MjA1ODc5In0=", "sortKey": "created_at DESC, post_id ASC" } }