Skip Main Navigation
Page Content

Batched Requests

To save on the added latency of doing several API requests at once - especially in high-latency environments like mobile data - it’s possible to do a batched request to the API and have our servers process all of your requests at once, saving you the cost of several request round trips.

Note

Batched requests currently execute serially on our servers, rather than in parallel, so they are not suitable for speeding up a set of very slow operations, but are much better for a large volume of quick operations.

To do a batched request, you can send a JSON-formatted list of your requests to the /batch/ endpoint using POST, as the POST parameter batch:

[
    {"method":"GET", "relative_url":"users/me"},
    {"method":"GET", "relative_url":"users/me/owned_events/"},
    {"method":"GET", "relative_url":"users/me/owned_events/?page=2"}
]

You can also send application/json as content-type by passing a double encoded JSON object:

{"batch": "[{\"method\":\"GET\", \"relative_url\":\"users/me/\"},
{\"method\":\"GET\", \"relative_url\":\"users/me/owned_events/\"},
{\"method\":\"GET\", \"relative_url\":\"users/me/owned_events/?page=2\"}]"}

And can pass request bodies (for e.g. POST data):

[
    {"method":"POST", "relative_url":"events/", "body":"event.name.html=Test&event.organizer_id=34"},
]

Warning

POST support is not yet complete, and will not pass any parameters. This documentation is here for future reference.

This results in a JSON formatted response, with one response entry for each request you submitted:

[
    {
        "body": "{\"emails\": [{\"email\": \"andrewgodwin@evbqa.com\", \"verified\": false, \"primary\": true}], \"id\": \"106645007774\", \"name\": \"andrewgodwin@evbqa.com\", \"first_name\": null, \"last_name\": null}",
        "headers": {
            "Content-Type": "application/json",
            "Access-Control-Allow-Origin": "*",
            "Vary": "Accept",
            "Allow": "GET, HEAD, OPTIONS"
        },
        "code": 200
    },
    {
        "body": "{\"pagination\": {...}, \"events\": [...]}",
        "headers": {
            "Content-Type": "application/json",
            "Access-Control-Allow-Origin": "*",
            "Vary": "Accept",
            "Allow": "GET, HEAD, OPTIONS"
        },
        "code": 200
    },
    {
        "body": "{\"status_code\": 400, \"error_description\": \"You passed an invalid page number.\", \"error\": \"BAD_PAGE\"}",
        "headers": {
            "Content-Type": "application/json",
            "Access-Control-Allow-Origin": "*",
            "Vary": "Accept",
            "Allow": "GET, HEAD, OPTIONS"
        },
        "code": 400
    }
]

A response has three keys:

  • body, which is a string containing the HTTP body of the request.
  • headers, a dictionary/object containing the HTTP headers of the response
  • code, an integer containing the HTTP status code of the response.

Notably, the response body will need additional decoding by your client before it can be parsed (it is not just broken out as separate JSON as it might contain different kinds of response data).

Errors appear in the individual responses - you can see above that one of the three responses has code 400 and is actually a BAD_PAGE error - but the overall response code of POST /batch/ will always be 200.