By path

Find how two entities are connected, shortest connections first.

POST/api/v2.0-preview/atlas/graphs/paths

Authorizations

Bearer

Authorizationstringrequiredheader

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

Example: Bearer nos_sk_...

Body

application/json

sourceobjectrequiredbody

An entity as {type, name}: type is ORG, PERSON, GPE, LOC or PRODUCT; name is matched case-insensitively, and an alias ("NVIDIA", "Trump") resolves to the entity it names. Names are World V2.0-preview's canonical names; for a ticker, send its company as an ORG.

Example: {"type":"ORG","name":"Nvidia"}

targetobjectrequiredbody

Example: {"type":"PERSON","name":"Sam Altman"}

max_hopsintegerbody

Longest path considered, 1 to 6. Defaults to 4.

Example: 3

max_pathsintegerbody

Paths returned, 1 to 25. Defaults to 5.

Example: 2

time_respectingbooleanbody

When true, each step's evidence is dated on or after the previous step's, and every step reports evidence_date.

Example: false

directionenumbody

in (the entity is the object), out (the entity is the subject) or both. Defaults to both.

Example: both

predicatesstring[]body

Keep only these relationship types (array of strings). List them with Relationship types.

Example: ["supplier_to"]

exclude_predicatesstring[]body

Drop these relationship types (array of strings).

Example: ["located_in"]

other_typesstring[]body

Keep only relationships whose other end has one of these entity types.

Example: ["ORG"]

exclude_typesstring[]body

Drop relationships where either end has one of these entity types.

Example: ["GPE","LOC"]

min_supportintegerbody

Minimum number of distinct supporting events inside the window. Defaults to 1.

Example: 10

aliasesenumbody

hide (default), include or only. Alias relationships are normalized_to (spelling variants) and alias_of (short names).

Example: hide

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 By path to explain a link between two entities. The shortest paths are exact; truncated is true only when a work budget stopped the search, in which case longer paths may exist that were not returned. Set time_respecting to require that each link was reported after the one before it. The example finds how Nvidia reaches Sam Altman over relationships with at least 10 supporting events: through OpenAI, which Nvidia invests in and where Sam Altman holds a position. Each relationship is a step of its own, so two relationship types between the same entities make two paths.

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.

pathsobject[]

[{length, steps: [{relationship, from, to, evidence_date}]}], shortest first.

graphobject

{nodes, edges, count, total, truncated}. nodes carry focus: true for the entities you asked about; edges are relationships, strongest first; total counts edges before the limit.

truncatedboolean

True when a work budget stopped the search.

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.