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.
Download OpenAPI description
Languages
Servers
https://api-prd.infra-prod.blackbird.ai/v1/
Bodyapplication/jsonrequired
Elasticsearch-style filter (and boolean query), sort, and pagination criteria.
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"}]
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" } }