Asynchronous requests

Asynchronous requests

Get Companies endpoint of Vainu API supports asynchronous operations. This is especially handy with complex queries or with larger datasets, where response times might be slower.

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.

🚧

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.