Skip to main content

Async Requests

Overview​

Some Source Systems can be slow when fetching a large amount of data. In those situations, you might wish to instruct Agave to process the request asynchronously in the background without your request hanging.

info

Only requests that return JSON responses can be processed asynchronously. As a result, the /passthrough-download or /download endpoints will not work with the Async-Request header.

info

This endpoint only works with response payloads smaller than 2MB. If the results is larger, you will receive a 413 Content Too Large response.

To instruct Agave to execute a request asynchronously, you pass the Async-Request: true header with your request. The response will include a Agave-Async-Request-Id header which can be used with the /async-requests/{id} endpoint.

To see a full list of response headers, refer to Headers.

Polling Frequency​

Requests to the /async-requests/{id} endpoint count towards your API Usage. To prevent your Linked Account from being rate limited and stay within our Rate Limits, we recommend a polling frequency of no shorter than every 5 seconds.

Example​

Execute Request​

The below example executes an API request asynchronously:

curl --request GET https://api.agaveapi.com/projects?expand=1 \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Account-Token: account_token' \
     --header 'Async-Request: true'

The response will look something like this:

HTTP/1.1 202 Accepted

Content-Type: application/json
Date: Thu, 27 Apr 2023 22:50:25 GMT
Agave-Async-Request-Id: 0187c4e9-04be-72d4-94dd-35b4a88cd81d
Agave-Async-Request-State: pending
Agave-Async-Request-Started-At:
Agave-Async-Request-Finished-At:
Agave-Async-Request-Expires-At: 2023-04-27T23:50:18Z
Agave-Request-Id: 88cb8e15f361a62514d24e0189915059
Agave-RateLimit-Total: 600
Agave-RateLimit-Remaining: 597

<no response body>

Fetching Results​

To fetch the results, you send a request to the /async-requests/{id} endpoint.

Request:

curl --request GET https://api.agaveapi.com/async-requests/0187c4e9-04be-72d4-94dd-35b4a88cd81d \
     --header 'API-Version: 2021-11-21' \
     --header 'Client-Id: your_client_id' \
     --header 'Client-Secret: your_client_secret' \
     --header 'Account-Token: account_token'

Response: The response you get depends on the state of the Async Request. If the state is pending or running, you need to keep calling the endpoint every 5-10 seconds to see if the Request has executed or not.

The Request is still pending and has not yet started.

HTTP/1.1 202 Accepted

Content-Type: application/json
Date: Thu, 27 Apr 2023 22:50:25 GMT
Agave-Async-Request-Id: 0187c4e9-04be-72d4-94dd-35b4a88cd81d
Agave-Async-Request-State: pending
Agave-Async-Request-Started-At: 
Agave-Async-Request-Finished-At: 
Agave-Async-Request-Expires-At: 2023-04-27T23:50:18Z
Agave-Request-Id: 88cb8e15f361a62514d24e0189915059
Agave-RateLimit-Total: 600
Agave-RateLimit-Remaining: 597

<no response body>