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.

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

Project

Operations

Posts

Operations

Narratives

Operations

Authors

Operations

Search for authors

Request

The Authors endpoint allows you to fetch authors of content that Constellation has analyzed. Each author includes bio information, summary statistics of posts and account info, and an assessment of their profile.

Query
projectIdstringrequired

The ID of the project to find 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(AuthorsSearchRequestDto__schema0)
Any of:
booleanstring

A lucene query to filter on author 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/authors/-/search?projectId=string' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "bool": {
        "must": [
          {
            "range": {
              "followers": {
                "gte": 1000,
                "lte": 100000
              }
            }
          }
        ],
        "should": [
          {
            "term": {
              "platform": "twitter"
            }
          },
          {
            "term": {
              "platform": "reddit"
            }
          }
        ]
      }
    },
    "sort": [
      {
        "field": "followers",
        "direction": "DESC"
      },
      {
        "field": "authorId",
        "direction": "ASC"
      }
    ],
    "page": {
      "first": 50,
      "after": "eyJhdXRob3JJZCI6IjEyMzQ1Njc4OSIsImZvbGxvd2VycyI6MTAwMDB9"
    }
  }'

Responses

Bodyapplication/json
authorsArray of objectsrequired
Example: [{"authorId":"1324f3rcdq34cwq3sxwerc23"}]
authors[].​allAuthorTextstring

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.

authors[].​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.

authors[].​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.

authors[].​accountCreatedAtstring(date-time)

The date the the author created their account. (ISO 8601, UTC)

authors[].​bioLocationstring

The author's stated location.

authors[].​bioUrlstring

The author's website URL.

authors[].​cohortsobject

Author classification cohorts. Query as author.cohorts:Label>=0.5

authors[].​displayNamestring

The author's display name.

authors[].​followersnumber

Number of followers the author has.

authors[].​followingnumber

Number of accounts the author follows.

authors[].​isBotLikeboolean

Whether the author was determined to be a bot or not.

authors[].​platformstring

The platform the author is on.

authors[].​postCountnumber

Total number of posts by the author.

authors[].​profileBiostring

The author's profile description/bio.

authors[].​usernamestring

The author's username/handle.

authors[].​authorIdstringrequired

The unique identifier for the author of the post.

Example: "1324f3rcdq34cwq3sxwerc23"
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
{
  "authors": [
    { … }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "endCursor": "eyJjcmVhdGVkQXQiOiIyMDI1LTA4LTI3VDAxOjAwOjEyLjAwMFoiLCJwb3N0SWQiOiIxOTYwNTA3NjA3Njg2MjA1ODc5In0=",
    "sortKey": "created_at DESC, post_id ASC"
  }
}