Skip to content

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
constellation.json
constellation.yaml
Languages
Servers
https://api-prd.infra-prod.blackbird.ai/v1/

Project

Operations

Posts

Operations

Search for posts

Request

The Posts endpoint allows you to fetch social posts that have been processed and enriched by Constellation. Each post includes its original content—such as text, author information, and engagement data—along with enrichments that provide deeper analytical context.

Query
projectIdstringrequired

The ID of the project to for records within

Bodyapplication/jsonrequired

Query, sort, and pagination criteria.

Cursor-Based Pagination:

  • For the first page, omit the after field or set it to null
  • Use the endCursor value from the previous response's pageInfo as the after value for the next page
  • The cursor is an identifier to the last row in the previous page
  • Example cursor: eyJjcmVhdGVkQXQiOiIyMDI1LTA4LTI3VDIwOjQ4OjI4LjAwMFoiLCJwb3N0SWQiOiIxOTYwODA2NjQyMjE3NTc0NTAyIn0=

Pagination Flow:

  1. First request: { "query": {...}, "page": { "first": 50 } }
  2. Response includes: pageInfo.endCursor
  3. Next request: { "query": {...}, "page": { "first": 50, "after": "<endCursor from previous>" } }
queryobject(PostsSearchRequestDto__schema0)
Any of:
booleanstring

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.

sortArray of objects

A list of fields to sort by.

pageobject

Pagination information.

Default {"first":50}
curl -i -X POST \
  'https://api-prd.infra-prod.blackbird.ai/v1/posts/-/search?projectId=string' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "bool": {
        "must": [
          {
            "range": {
              "createdAt": {
                "gte": "2025-01-01T00:00:00Z",
                "lte": "2025-11-05T23:59:59Z"
              }
            }
          }
        ],
        "should": [
          {
            "term": {
              "platform": "twitter"
            }
          },
          {
            "term": {
              "platform": "reddit"
            }
          }
        ]
      }
    },
    "sort": [
      {
        "field": "createdAt",
        "direction": "DESC"
      },
      {
        "field": "postId",
        "direction": "ASC"
      }
    ],
    "page": {
      "first": 50,
      "after": "eyJwb3N0SWQiOiIxOTYwODA2NjQyMjE3NTc0NTAyIiwiY3JlYXRlZEF0IjoiMjAyNS0wOC0yN1QyMDo0ODoyOC4wMDBaIn0="
    }
  }'

Responses

Bodyapplication/json
postsArray of objectsrequired
Example: [{"postId":"1960806642217574502","narrativeId":"429","createdAt":"2025-08-27T20:48:28.000Z","platform":"twitter","text":"RT @Jansant: @MichaelWestBiz @AlboMP Over the weekend 300k march to sanction Israel..."}]
posts[].​allAuthorTextstring

Search across all author text fields - author.username, author.displayName, author.description, author.location. NOTE - Not actually returned as a field in the response, but documented here to facilitate describing the filterability.

posts[].​allNarrativeTextstring

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.

posts[].​allPostTextstring

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.

posts[].​anomalousScorenumber

Behavioral Manipulation score from the BBMI model.

posts[].​authorobject
posts[].​authorIdstring

The unique identifier for the author of the post.

posts[].​createdAtstring(date-time)^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[...required

The timestamp when the post was created.

Example: "2025-08-27T20:48:28.000Z"
posts[].​domainobject
posts[].​langstring

The detected language of the post content (e.g., 'en', 'es').

posts[].​narrativeIdstring

The unique identifier for the narrative.

Example: "429"
posts[].​parentIdstring

The ID of the post's direct parent.

posts[].​platformstringrequired

The platform where the post originated (e.g., Twitter, Reddit, Telegram).

Example: "twitter"
posts[].​postIdstringrequired

The unique identifier for the post.

Example: "1960806642217574502"
posts[].​postUrlstring

The original URL of the post.

posts[].​textstring

The main text content of the post. Not exposed for twitter or reddit posts. Use the postUrl to get it.

Example: "RT @Jansant: @MichaelWestBiz @AlboMP Over the weekend 300k march to sanction Israel..."
posts[].​titlestring

The title of the post (e.g., for Reddit submissions or articles). Not exposed for twitter or reddit posts. Use the postUrl to get it.

posts[].​updatedAtstring(date-time)^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[...

The timestamp when the post was last updated.

pageInfoobjectrequired
Example: {"hasNextPage":true,"endCursor":"eyJjcmVhdGVkQXQiOiIyMDI1LTA4LTI3VDAxOjAwOjEyLjAwMFoiLCJwb3N0SWQiOiIxOTYwNTA3NjA3Njg2MjA1ODc5In0=","sortKey":"created_at DESC, post_id ASC"}
pageInfo.​hasNextPagebooleanrequired
Example: true
pageInfo.​endCursorstring
Example: "eyJjcmVhdGVkQXQiOiIyMDI1LTA4LTI3VDAxOjAwOjEyLjAwMFoiLCJwb3N0SWQiOiIxOTYwNTA3NjA3Njg2MjA1ODc5In0="
pageInfo.​totalCountnumber
pageInfo.​sortKeystring
Example: "created_at DESC, post_id ASC"
Response
application/json
{
  "posts": [
    { … }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "eyJjcmVhdGVkQXQiOiIyMDI1LTA4LTI3VDAxOjAwOjEyLjAwMFoiLCJwb3N0SWQiOiIxOTYwNTA3NjA3Njg2MjA1ODc5In0=",
    "sortKey": "created_at DESC, post_id ASC"
  }
}

Narratives

Operations