Rank entities

Rank the most important entities in a graph (personalised PageRank).

POST/api/v2.0-preview/atlas/analysis/rankings

Authorizations

Bearer

Authorizationstringrequiredheader

Required Bearer API key: your NOSIBLE API key from the API Dashboard.

Example: Bearer nos_sk_...

Body

application/json

graphobjectrequiredbody

The graph to analyse: the same object as the By entity body (entities, hops 1 to 3 defaulting to 2, and the filters). as_of and from go at the top level, not inside graph. Scope is capped at 100,000 entities.

Example: {"entities":[{"type":"ORG","name":"Nvidia"},{"type":"ORG","name":"AMD"},{"type":"ORG","name":"Intel"},{"type":"ORG","name":"TSMC"}],"hops":1,"exclude_types":["GPE","LOC"],"min_support":5}

seedsobject[]body

Entities the ranking is personalised to, up to 100. Defaults to the graph's entities.

Example: [{"type":"ORG","name":"OpenAI"}]

limitintegerbody

Entities returned. Defaults to 25, maximum 500.

Example: 5

as_ofdatebody

Point in time (YYYY-MM-DD). Only events dated on or before it count. Defaults to the latest date in the release. `to` is accepted as the same parameter, as in the World API.

Example: 2024-12-31

fromdatebody

Optional start of the evidence window (YYYY-MM-DD, inclusive).

Example: 2020-01-01

How to use this endpoint

guidance

Use Rank entities to find what matters most around your entities, from the point of view of the seeds. Scores are personalised PageRank (damping 0.85) over relationships weighted by support; identical requests give identical answers. A seed need not be one of the entities the graph is built from, only in the graph: the example ranks the graph around four chipmakers for OpenAI, so the chipmakers closest to OpenAI, Nvidia and AMD, rank above Intel and TSMC.

Response body

application/json

These are the fields you can build against. Nested names use dot notation; optional sections are called out in their descriptions.

rankingobject[]

[{rank, entity, score}], highest score first.

seeds_outside_graphobject[]

Seeds the graph does not contain, so they could not personalise the ranking. When none of the seeds is in the graph, the ranking is personalised to the graph's entities instead.

scopeobject

{nodes, edges, truncated}: the size of the graph analysed.

approximateboolean

True when the answer comes from sampling or an iteration cap.

schemastring

Response schema name.

as_ofdate

The point in time the answer is computed for.

date_windowobject

The evidence window: from, to, archive_cutoff and include_live (always false).

releasestring

Immutable id of the graph release that answered. The same request against the same release returns identical bytes.

took_msinteger

Server time in milliseconds.

Responses and errors

HTTP

200Request succeeded. The response body is shown in the panel on the right.

400invalid_request — A parameter is missing, malformed or out of range; the message names it.

400invalid_entity_type — The entity type is not one Atlas holds. TICKER is refused: send the company as an ORG.

400unknown_predicate — A relationship type is not in the graph; list them with Relationship types.

401api_key_required — No API key was sent. Send it as Authorization: Bearer <key> or the api-key header.

401invalid_api_key — The API key is invalid or has been revoked.

404unknown_entity — No entity of that type has that name in this release. When the name exists under another type, the message says which.

404not_found — No endpoint matches this method and path.

410cursor_expired — The cursor belongs to another release or request; restart from the first page.

422unprocessable_request — Each value is valid but not together, such as from after as_of.

422request_too_broad — The request ran out of its work budget before it could answer; narrow it.

429rate_limited — Too many requests for this key; wait for Retry-After.

501backend_not_configured — The Atlas backend is not configured for this deployment.

502backend_error — The Atlas backend could not be reached; retry shortly.

503unavailable — The service is busy or starting; retry after Retry-After.

503api_key_auth_unavailable — API key authentication is temporarily unavailable; retry shortly.

504request_timeout — The request took longer than 25 seconds; narrow it.

504backend_timeout — The Atlas backend did not answer before the deadline; retry.