Atoka API User Reference

v20260625.1415

Timeline Event Search

Returns events associated with an entity (company, person, etc.). Events are ordered by endDate descending by default, with events without an endDate being treated as most recent ones; configurable via the ordering parameter. Use the after cursor parameter for pagination.

https://api.atoka.io/v2/timeline

All requests must be properly authenticated.

General info

In this section we grouped together filters that apply to the general information of timeline events, such has their type, the period they reference to and the entities they are about. This is the starting point for trying out the Timeline Search API.

Parameters

  • ids array

    Filter by one or more known Event IDs. Mutually exclusive with the companies parameter: they cannot be used together.

    Accepts multiple values, separated with , (comma) char.

  • companies array

    Filter by one or more known Subject Company IDs. Mutually exclusive with the ids parameter: they cannot be used together.

    Accepts multiple values, separated with , (comma) char.

  • eventTypes array required

    Filter by one or more known event types.

    Accepts multiple values, separated with , (comma) char.

  • startDateFrom string

    Filter events with a startDate equal or more recent than the given value. Use ISO 8601 date format.

  • startDateTo string

    Filter events with a startDate less recent than the given value. Use ISO 8601 date format.

curl -G "https://api.atoka.io/v2/timeline" -d "ids=MSEnjsZVhG1YBEY_a2UcZ" -d "companies=00161c6fcab3" -d "eventTypes=cebi-micro-score" -d "startDateFrom=2020-01-01" -d "startDateTo=2024-12-31"

Response

By default this API endpoint returns the list of timeline events matching the selected criteria.

Using these parameters, you'll be able to customize the output you'll get from your searches.

Parameters

  • fields array,
    default is items

    Get just the list of timeline events matched.

    If you set this to value none, you'll get just the meta object, with count of timeline events matching your search criteria.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

    • items
    • none
curl -G "https://api.atoka.io/v2/timeline" -d "fields=items"

Response modifications

When fields is items, the response will be:

{
"items": [
{
"id": "foo",
"subjects": [
{
"id": "foo",
"entityType": "foo",
"label": "foo"
},
...
],
"eventType": "cebi-micro-score",
"startDate": "2015-12-24",
"endDate": "2015-12-24",
},
...
],
"meta": {
"count": 34,
"limit": 34,
"after": "MjAxMy0xMi0zMXxjZWJpLW1pY3JvLXNjb3JlfE1TRUtHSWh0QUVyTHRjMHZkRTNm",
"info": [
"foo",
...
]
}
}
curl -G "https://api.atoka.io/v2/timeline" -d "fields=items"

Ordering & Pagination

To download long lists of results you can paginate returned items using these parameters.

You can also decide the order in which items are returned.

Parameters

  • after string

    Cursor for pagination - the id of the last event received

  • ordering string,
    default is "mostRecent"

    Selects the order in which results are returned. Events without endDate are treated as most recent.

    Choose only one among:

    • mostRecent
    • leastRecent

  • limit integer,
    default is 10

    This is the number of individual objects that are returned in each page.

    Use a number between 0 and 50.

curl -G "https://api.atoka.io/v2/timeline" -d "after=MSEcGavCIyKt5ZnPDsZ9" -d "ordering=mostRecent" -d "limit=10"

Data Packages

Parameters

  • packages array

    With payload as its only value, allows to display the content of the event.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

curl -G "https://api.atoka.io/v2/timeline" -d "packages=payload"

Authentication

Parameters

  • token string required

    All requests must be properly authenticated; see the Authentication section for more info

curl -G "https://api.atoka.io/v2/timeline"

Debug

Use these parameters when you need to understand how your request was evaluated by the API.

Parameters

  • explain boolean,
    default is false

    When using this parameter in your request you'll get and additional property in the results explanation, that contains all the filters actually used during the query.

    Mostly useful for debugging purposes.

curl -G "https://api.atoka.io/v2/timeline" -d "explain=true"

Response modifications

When explain is true, the response will be:

curl -G "https://api.atoka.io/v2/timeline" -d "explain=true"

Response

List of Timeline Events

{
"items": [
{
"id": "foo",
"subjects": [
{
"id": "foo",
"entityType": "foo",
"label": "foo"
},
...
],
"eventType": "cebi-micro-score",
"startDate": "2015-12-24",
"endDate": "2015-12-24",
},
...
],
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
],
"meta": {
"count": 34,
"limit": 34,
"after": "MjAxMy0xMi0zMXxjZWJpLW1pY3JvLXNjb3JlfE1TRUtHSWh0QUVyTHRjMHZkRTNm",
"info": [
"foo",
...
]
}
}

Timeline Event Details

Show the details of a timeline event

https://api.atoka.io/v2/timeline/{id}

Replace {id} with the event ID you want details for (as returned by the Timeline Event Search API)..

All requests must be properly authenticated.

Data Packages

Parameters

  • packages array

    With payload as its only value, allows to display the content of the event.

    Accepts multiple values, separated with , (comma) char: will match on any value (logic OR).

    Possible values are:

curl -G "https://api.atoka.io/v2/timeline/{id}" -d "packages=payload"

Authentication

Parameters

  • token string required

    All requests must be properly authenticated; see the Authentication section for more info

curl -G "https://api.atoka.io/v2/timeline/{id}"

Debug

Use these parameters when you need to understand how your request was evaluated by the API.

Parameters

  • explain boolean,
    default is false

    When using this parameter in your request you'll get and additional property in the results explanation, that contains all the filters actually used during the query.

    Mostly useful for debugging purposes.

curl -G "https://api.atoka.io/v2/timeline/{id}" -d "explain=true"

Response modifications

When explain is true, the response will be:

curl -G "https://api.atoka.io/v2/timeline/{id}" -d "explain=true"

Response

Details of a Timeline Event

{
"item": {
"id": "foo",
"subjects": [
{
"id": "foo",
"entityType": "foo",
"label": "foo"
},
...
],
"eventType": "cebi-micro-score",
"startDate": "2015-12-24",
"endDate": "2015-12-24",
},
"queryExplanation": [
{
"engine": "foo",
"text": "foo",
"json": {"foo": "bar"}
},
...
]
}