Entity directory

Enumerate Atlas canonical entities, most mentioned first: lite records by default, with each entity's observed metadata on view=full.

GET/api/v2.0/entities

Authorizations

Bearer

Authorizationstringheader

Required Bearer API key for programmatic World access.

Example: Bearer nos_sk_...

Parameters

query & path

viewenumquery

The records returned: lite (the default), each entity's or ticker's identity, event count, date range and events per year, enough to choose one and fetch its events; or full, which adds the facets and numeric statistics of its events and a ticker's complete reference data. Any other value is a 422 validation_error.

Example: lite

typestringquery

Optional NER type such as ORG or PERSON, or ANY: ANY looks each entity type up under the name it indexes and lists the union, as the entity_any filter does.

Example: ORG

pageintegerquery

1-based page number of limit entities. Ignored when cursor is sent.

Example: 1

limitintegerquery

Entries per page: 1 to 500 with view=lite, 1 to 100 with view=full. Defaults to 50.

Example: 50

min_eventsintegerquery

Only entries with at least this many events. Defaults to 1. The directory is in event order, so this cuts its long tail: most names have one or two events.

Example: 10

cursorstringquery

next_cursor of the previous page, to walk the whole directory. A cursor belongs to one index build and one set of filters (type, min_events): after the daily index rebuild it is refused with 410 cursor_expired, so start again from the first page. page is ignored when cursor is sent.

How to use this endpoint

guidance

In V2.0, the directory lists Atlas's normalized entities: each canonical entity once, with its spellings and short names folded in. Use Entity directory to list or mirror the entities World indexes. Page through with page and limit, or walk the whole directory with next_cursor, which stays on one index build. min_events cuts the long tail of names seen once or twice, and type keeps one NER type. Lite records (the default) carry what you need to choose an entity and fetch its events; view=full adds the facets and numeric statistics of its events, as Entity profile returns them.

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.

schemastring

Response schema name.

viewstring

The view of the records: lite (the default) or full.

entity_typestring | null

The type filter, null for every type.

coveragestring

What the directory enumerates: indexed_entity_vocabulary.

orderstring

mentions_desc: the most-mentioned entities first.

pageinteger

1-based page number: the page of limit entries this response starts in.

limitinteger

Entries per page applied.

min_eventsinteger

Fewest events an entry has, as requested (1 by default).

totalinteger

Entries in the directory with the request's type and min_events.

has_moreboolean

Whether entries follow this page.

next_cursorstring | null

Send it back as cursor for the next page; null after the last. It expires with the index build.

entitiesobject[]

Up to limit Atlas canonical entities, each once, with the counts of all its names folded in.

entities[].kindstring

entity.

entities[].typestring

NER type of the entity, such as ORG or PERSON.

entities[].namestring

The entity's canonical Atlas name.

entities[].normalizedstring

Lower-cased lookup form of the name.

entities[].total_eventsinteger

Indexed events that mention the entity under any of its names.

entities[].first_datedate

Date of the earliest indexed event.

entities[].last_datedate

Date of the latest indexed event.

entities[].events_urlstring

The entity's event timeline on this API version.

entities[].metadataobject

What the indexed events of this entity look like: events_by_year, and with view=full facets (the top 20 values of each categorical event field, such as language, country, sentiment and every taxonomy level) and numeric (count, missing, sum, min, max and mean of lat, lng, total_coverage, total_netlocs, coverage_concentration_index and materiality_score).

entities[].metadata.events_by_yearobject[]

Events per year: {year, count}, every year of the archive.

entities[].metadata.facetsobject

view=full only. Top values of each categorical field: {field: [{value, count}]}.

entities[].metadata.numericobject

view=full only. Summary statistics of each numeric field.

entities[].filterobject

Ready-made World Search filter for the entity.

as_ofobject

index_build and archive_cutoff: the index that answered.

took_msinteger

Server time in milliseconds.

Responses and errors

HTTP

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

400invalid_json — The request body is not JSON. Every error body, 401 included, is {error, message, status}.

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.

403access_denied — The requested archive date is outside the caller's World tier.

422validation_error — The request is well formed but the API cannot decode or validate it: an unknown body field or query parameter, a missing required parameter, a value of the wrong type, an empty and, or or not, a date that is not a calendar date (in the path, the query or the body), an unknown enum value or a reversed range. The message names the parameter and what is wrong.

404not_found — The requested date, entity, ticker, or event does not exist in the accessible index.

410cursor_expired — The cursor was minted against a replaced index build. Restart pagination from the first page.

429rate_limited — The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.

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

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

503api_key_metering_unavailable — API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.

502backend_error — The World backend could not be reached or did not return a valid response; retry shortly.

504backend_timeout — The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.

422invalid_entity_type — The type filter is not one of the indexed NER types or ANY.

503inverted_index_unavailable — The entity directory index is not loaded; retry after the next index publish.

422cursor_invalid — The cursor could not be read; start again from the first page.

422cursor_filter_mismatch — The cursor belongs to a walk with another type or min_events; drop it to start a new walk.

410cursor_expired — The index was rebuilt since the cursor was issued, which reorders the directory; start again from the first page.