This is a constellation 🌌 API server from microcosm ✨

Constellation is a self-hosted JSON API to an atproto-wide index of PDS record back-links, so you can query social interactions in real time. It can answer questions like:

• How many people liked a liked a bluesky post?
• Who are all the bluesky followers of an identity?
• What are all the replies to a Frontpage submission?
• What are all the sources of links to an identity?
• and more

It works by recursively walking all records coming through the firehose, searching for anything that looks like a link. Links are indexed by the target they point at, the collection the record came from, and the JSON path to the link in that record.

This server has indexed 2,191,096,038 links between 342,211,586 targets and sources from 11,698,566 identities over 46 days.
(indexing new records in real time, backfill still TODO)

The API is currently unstable. But feel free to use it! If you want to be nice, put your project name and bsky username (or email) in your user-agent header for api requests.

API Endpoints

GET /links

A list of records linking to a target.

Query parameters:

• target: required, must url-encode. Example: at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r
• collection: required. Example: app.bsky.feed.like
• path: required, must url-encode. Example: .subject.uri

Try it:

GET /links
  ?target=     
  &collection= 
  &path=        get links

GET /links/distinct-dids

A list of distinct DIDs (identities) with links to a target.

Query parameters:

• target: required, must url-encode. Example: at://did:plc:vc7f4oafdgxsihk4cry2xpze/app.bsky.feed.post/3lgwdn7vd722r
• collection: required. Example: app.bsky.feed.like
• path: required, must url-encode. Example: .subject.uri

Try it:

GET /links/distinct-dids
  ?target=     
  &collection= 
  &path=        get links

GET /links/count

The total number of links pointing at a given target.

Query parameters:

• target: required, must url-encode. Example: did:plc:vc7f4oafdgxsihk4cry2xpze
• collection: required. Example: app.bsky.graph.block
• path: required, must url-encode. Example: .subject
• cursor: optional, see Definitions.

Try it:

GET /links/count
  ?target=     
  &collection= 
  &path=        get links count

GET /links/count/distinct-dids

The total number of DIDs (identities) with links to at a given target.

Query parameters:

• target: required, must url-encode. Example: did:plc:vc7f4oafdgxsihk4cry2xpze
• collection: required. Example: app.bsky.graph.block
• path: required, must url-encode. Example: .subject
• cursor: optional, see Definitions.

Try it:

GET /links/count/distinct-dids
  ?target=     
  &collection= 
  &path=        get links count

GET /links/all

Show all sources with links to a target, including linking record counts and distinct linking DIDs

Query parameters:

• target: required, must url-encode. Example: did:plc:oky5czdrnfjpqslsw2a5iclo

Try it:

GET /links/all?target= get all target link counts

[deprecated] GET /links/all/count

The total counts of all links pointing at a given target, by collection and path.

DEPRECATED: Use GET /links/all instead.

Query parameters:

• target: required, must url-encode. Example: did:plc:oky5czdrnfjpqslsw2a5iclo

Try it:

GET /links/all/count?target= get all target link counts

Definitions

Target

A DID like did:plc:hdhoaan3xa3jiuq4fg4mefid, or an AT-URI like at://did:plc:z72i7hdynmk6r22z27h6tvur/app.bsky.feed.post/3lgu4lg6j2k2v, or a URI like https://example.com.

Collection

A record NSID like app.bsky.feed.like.

Path

A (currently-very-very-hacky) json-path-ish representation of the source of a link in a record. Records may contain multiple links with different meanings, so this specifies which specific link is of interest. Like .subject.uri.

Cursor

Paged responses include a cursor property. When it's null, no more data is available. If it's not null, you can repeat the request with &cursor=<cursor> in the URL query to get the next set of responses.