Asynchronous Requests

When to Use Async

Use the async endpoint when:

Query involves large datasets - Without pagination!
Response time might exceed 2 minutes
Processing hundreds of thousands or even millions of records
Use streaming formats (CSV, JSONL) for big data

Endpoint /async/

Endpoint accepts exactly same payload as with synchronous API requests. Add /async/ to the synchronous endpoint. For example Async Organizations Endpoint:

POST https://api.vainu.io/api/v3/organizations/async/

This endpoint returns a data structure that can be polled on until job is completed.

Basic Flow

Vainu v3 async endpoints — three steps

Using Vainu API authenication poll the link in the returned json data str
If state is accepted or processingkeep polling every couple of seconds
When stateis completed download the data from download_link

Basic Usage - Example

For full async example check this recipe:

Async Request Parameters

Define the Output Format for Asynchronous Jobs

Set the format directly to the url. Default format is json. For bigger datasets you must uses streamable formats like jsonl and csv

POST https://api.vainu.io/api/v3/organizations/async/?async_format=csv
POST https://api.vainu.io/api/v3/organizations/async/?async_format=jsonl

Async Request Response - Job Status

Async API returns data structure that describes the job status.

Field	Description	type
created	When the async job was created	datetime
download_link	Download your data here. For security, this link uses a short-lived authentication token and is only valid for a limited time. Available when `state is 'completed'.`	str[url]
duration	Duration in seconds of the async job	int
finished	When job was finished	datetime
id/job_id	Id of the job. Can be seen in the link	str
link	Link that can be polled for this async job using Vainu API Authentication.	str[url]
owner	Vainu user name that request the job	str
progress	How many records have been processed so far	int
state	State of job `accepted, process, completed, failure`	str
error/error_msg	With `state` is `failure`'. Some information why your task failed. Contact Vainu Support for more information.	str

Job States

State	Meaning	Action
`accepted`	Job received and queued	Continue polling
`process`	Job is running	Continue polling
`completed`	Job finished successfully	Download results from `download_link`
`failure`	Job failed with error	Check error details or contact Vainu support.

Example Response

Both initial and polled responses return the same data structure:

{
    "created": "2026-04-16T14:03:24.739648",
    "download_link": null,
    "duration": "0.01",
    "finished": null,
    "id": "69e0ec2c584defb85b0dbd68",
    "job_id": "69e0ec2c584defb85b0dbd68",
    "link": "https://api.vainu.io/api/v2/async_result/public-organizations-async-api/69e0ec2c584defb85b0dbd68/",
    "owner": "[email protected]",
    "progress": null,
    "state": "accepted",
    "error": null,
    "error_msg": null
}

Example: Completed Job

When job is completed data can be downloaded from the download_link. download_linkis a short-lived presigned url directly to storage. The link contains authentication token and can be used without Vainu API authentication.

{
    "created": "2026-04-16T14:03:24.739000",
    "download_link": "https://vainu-exports...",
    "duration": "30",
    "finished": "2026-04-16T14:33:25.335000",
    "id": "69e0ec2c584defb85b0dbd68",
    "job_id": "69e0ec2c584defb85b0dbd68",
    "link": "https://api.vainu.io/api/v2/async_result/public-organizations-async-api/69e0ec2c584defb85b0dbd68/",
    "owner": "[email protected]",
    "progress": 130,
    "state": "completed",
    "error": null,
    "error_msg": null
}

Polling Strategy

Check out the recipe for full code example.

result_url - Load resulting data directly to your Storage

User result_urlto load the data directly to your Storage such as AWS S3, Google Storage or Azure Blob Storage.

Example Flow:

Generate a presigned url to your Storage and included it when requesting async job with API. The resulting data is directly loaded to your storage.

`payload = {
    "list": LIST_ID
    "fields": [
        "business_id",
        "name",
        "website"
    ],
    "limit": 1000000,
    "result_url": "https://your.storage.com/presigned_url...",
}`

response = requests.post(organizations_endpoint, headers=headers, json=payload)
print(response.json())