Asynchronous requests

Use /api/companies/async/ endpoint of Vainu API for asynchronous operations. End point functions and supports all the same parameters as synchronous version of the API /api/companies/ . For example specifying the query, fields, formatting options and limit/offset. Only difference is with asynchronous requests, Vainu API responds with job details or begins a process to generate a file to be downloaded. API can be used for follow-up queries to get the status of the job and eventually to get a download_link for the response.

This is especially handy with complex queries or with larger datasets, where response times might be slower.

For long and complex and large data deliveries

Our synchronous /api/companies/ API has a 2 minute timeout. Any request that takes longer should use async.

Specify Format with ?async_format

Default format is json always in our APIs. To specify the format for the data generated by async job use async_formatGET parameter.

/api/companies/async/?async_format=csv

For data deliveries with huge amount of data use formats `csv/jsons/jsonl`

If you are loading huge datasets of hundreds of thousands of results with a lot of fields use one of streamable format options:


`/api/companies/async/?async_format=jsons`	JSON format, but streamed through a different JSON formatter, so there could theoretically be some differences compared to the standard JSON we provide
`/api/companies/async/?async_format=jsonl`	JSONLines format https://jsonlines.org/
`/api/companies/async/?async_format=csv`	Comma-separated values format https://developers.vainu.com/docs/csv

🚧
Limit for asynchronous request
Note that the default maximum limit of 1000 returned objects applies to the asynchronous endpoint. This can be changed. Contact your Vainu representative or support for requests.

Making an asynchronous task

Asynchronous endpoint has a separate endpoint but utilizes the same filtering capabilities as a normal GET companies endpoint. Instead of an immediate response, the API will respond with the job ID and details.

Following fields will be included in the initial and follow-up request responses.

Data field	Data type	Description
created	date-time	Timestamp when the job was created
download_link	string	Link where completed data may be requested
duration	string	Duration the job has been running
finished	date-time	Timestamp when the job was completed
job_id	string	Unique id for the job
link	string	Link to request the status of the job. Response is identical to the initial request
state	string	State of the job. Expected statuses are accepted, process, completed, and failure

Status of the asynchronous task

The initial response of the initiated job includes a field called link. This field may be used for follow-up queries to see the state and job details. The response will be identical to the first request.

Expected states of the job are following

State	Description
accepted	Job has been accepted by Vainu and processing will begin shortly
completed	Job has been completed and is ready for download
failure	Job has failed due to error.
process	Job is in process and will be completed shortly.

Getting results of a completed task

When the job state is "completed" the results can be downloaded from the download_link found at the initial or follow-up responses. You can either use the link to download the file or do a simple GET request to get the response programmatically.

Response and data included will be as stated in the initial request. See the Filtering and Response data guides for further instructions on how to manage response data.