Collecting data in Management API

Required body parameters

start

The first day of the date range for which to collect data (expressed as UTC).

end

The last day of the date range for which to collect data (expressed as UTC).

Optional body parameters

callback

Include a URL that is called once the fetch has been completed. Callback information you receive at the specified URL includes the filename, creation date, datastream name, Stack name, file size, number of collected rows, number of collected columns, and fetch status. An example of the string you may include in the request body is the following: "callback":"https://CALLBACK_URL"

priority

To change the priority of a task, use the priority parameter in the request body. To specify where the new task is placed in the task queue, use one of the following:

• Use "priority": "high" to assign the task a high priority. Adverity places the task at the top after tasks with high priority.

• Use "priority": "default" to assign the task the default priority set in your Adverity instance. This is usually high priority.

• Use "priority": "low" to assign the task a low priority. Adverity places the task at the end of the task queue.

• Use "priority": "backdata" for background data updates. Adverity will perform the task when nothing else is running.

interval

Split a single fetch into multiple smaller fetches covering the requested date range, similar to the Split into smaller fetches option in the Adverity user interface. Use one of the following values: daily, weekly, monthly, or quarterly. Only supported when running a fetch, not when triggering scheduled fetch jobs.

Running a fetch

By running a single fetch, you create one data extract with data in the defined date range from start to end. To run a single fetch of the data from a datastream, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/fetch_fixed/
   

2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the date range of your fetch in the following format:

   {
       "start":"YYYY-MM-DDTHH:MM:SSZ",
       "end":"YYYY-MM-DDTHH:MM:SSZ"
   }
   

5. (Optional) In the HTTP request body, include the parameter priority with value {{PRIORITY}}.

6. (Optional) In the HTTP request body, include the parameter interval to split the fetch into multiple smaller fetches. See Splitting a fetch into smaller fetches below.

7. Send the request.

Example of a valid response:

{
    "status": "ok",
    "message": "Fetch scheduled.",
    "start": "YYYY-MM-DDTHH:MM:SSZ",
    "end": "YYYY-MM-DDTHH:MM:SSZ",
    "jobs": [
        {
            "id": 123,
            "url": "https://{{INSTANCE}}/api/jobs/123/"
        }
    ]
}

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/fetch_fixed/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{KEY}}' \
--data-raw '{
    "start":"YYYY-MM-DDTHH:MM:SSZ",
    "end":"YYYY-MM-DDTHH:MM:SSZ",
    "priority":"{{PRIORITY}}"
}'

Splitting a fetch into smaller fetches

To split a single fetch into multiple smaller fetches covering the requested date range, include the interval parameter in the request body. This has the same effect as selecting Split into smaller fetches in the Adverity user interface. Accepted values are daily, weekly, monthly, and quarterly.

For example, the following request body creates one fetch per day for a four-day date range:

{
    "start":"2026-08-07T00:00:00Z",
    "end":"2026-08-10T23:59:59Z",
    "priority":"default",
    "interval": "daily"
}

As a result, Adverity creates one data extract per day within the date range — four data extracts in the example above. The jobs array in the response lists every fetch job that was created.

Triggering scheduled fetch jobs

To execute all scheduled fetch jobs within the selected date range, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/fetch/
   

2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the date range of your fetch in the following format:

   {
       "start":"YYYY-MM-DDTHH:MM:SSZ",
       "end":"YYYY-MM-DDTHH:MM:SSZ"
   }
   

5. Send the request.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/datastreams/{{DATASTREAM_ID}}/fetch/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "start":"YYYY-MM-DDTHH:MM:SSZ",
    "end":"YYYY-MM-DDTHH:MM:SSZ"
}'\

}'

Obtaining extract ID

To download a specific data extract, you need to know the extract ID. To obtain the extract ID, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/extracts/?datastream_id={{DATASTREAM_ID}}
   

2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

3. Send the request.

You can also filter extracts by creation date using the created_from and created_to query parameters (both expressed as UTC):

https://{{INSTANCE}}/api/extracts/?datastream_id={{DATASTREAM_ID}}&created_from=YYYY-MM-DDTHH:MM:SS&created_to=YYYY-MM-DDTHH:MM:SS

The cURL request example is the following:

curl --location --request GET \
  'https://{{INSTANCE}}/api/extracts/?datastream_id={{DATASTREAM_ID}}&created_from=YYYY-MM-DDTHH:MM:SS&created_to=YYYY-MM-DDTHH:MM:SS' \
  --header 'Authorization: Bearer {{KEY}}'

In the response, find the ID of the fetch job (first occurrence of the parameter id). In the procedure described below, use this ID as the {{EXTRACT_ID}} to retrieve the data extract.

Example of a part of a valid response:

{
    "count": null,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 123123,
            "created": "YYYY-MM-DDTHH:MM:SSZ",
            "datastream": {
                "id": 123,
                "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
                "stack": {
                    "id": 123,
                    "name": "name",
                    "slug": "name",
(...)

The first ID marked in red is the {{EXTRACT_ID}} needed for the procedure described in the following section. Use the JSONPath $.results[*].id to filter for all data extract IDs in your response. The first ID is the ID of the latest fetch. The last ID is the ID of the oldest fetch.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/extracts/?datastream_id={{DATASTREAM_ID}}' \
--header 'Authorization: Bearer {{KEY}}'

Downloading a specific data extract

To download a specific data extract, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/extracts/{{EXTRACT_ID}}/download/
   

2. In the HTTP request header, include the parameter Authorization with value Bearer {{KEY}}.

3. Send the request.

If the response status is 200, the response body contains the data extract file as a binary stream.

If the response status is 202, the data extract is being prepared asynchronously. The response body contains a task_id and a status_url (a pre-constructed URL to the status endpoint). Follow the steps in Handling asynchronous downloads to poll for completion and retrieve the file.

Import the request example as raw text to your HTTP client (such as Postman). The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/extracts/{{EXTRACT_ID}}/download/' \
--header 'Authorization: Bearer {{KEY}}'

curl --location --request GET 'https://{{INSTANCE}}/api/extracts/{{EXTRACT_ID}}/download/status/{{TASK_ID}}/' \
--header 'Authorization: Bearer {{KEY}}'

curl --location --request GET 'https://{{INSTANCE}}/api/extracts/{{EXTRACT_ID}}/download/ready/{{TASK_ID}}/' \
--header 'Authorization: Bearer {{KEY}}'