# Batch Requests

Issue multiple API requests at once

## Issue a batch request

> Combine multiple requests in a single batch and return a consolidated response.\
> \
> \## Request format\
> \
> Batch requests are always issued as \`POST\` requests.\
> \
> A batch request body consists of a single JSON object with one required\
> property: \`requests\`. The \`requests\` property is an array containing the\
> individual requests. For each of these requests, the following properties\
> are supported:\
> \
> \- \`operation\_id\`: \*\*Required\*\* The unique operation\_id corresponding to the endpoint action\
> \- \`name\`: \*\*Required\*\* A name to associate individual responses with requests.\
> In each batch, all requests should have unique names.\
> \- \`params\`: \*\*Optional\*\* An object containing the query params of the request, if any.\
> \- \`body\_params\`: \*\*Optional\*\* An object containing the body params of the request, if any.\
> \- \`path\_params\`: \*\*Optional\*\* An object containing the path parameters, if any.\
> Since we use the \`operation\_id\` to identify the endpoint to call, this property\
> is needed for endpoints containing path parameters. This is used for internal cases mostly.\
> See below for an example of this case.\
> \
> \
> {% hint style="info" %}\
> \
> \## Batch request example\
> \
> \
> In the following example, we will fetch both popular and trending events\
> in a single request.\
> \
> \`\`\`json\
> {\
>   "requests": \[\
>     {\
>       "operation\_id": "get\_popular\_events",\
>       "name": "1",\
>       "params": {\
>         "count": "10",\
>         "filters": "sport:eq:Soccer"\
>       }\
>     },\
>     {\
>       "operation\_id": "get\_trending\_events",\
>       "name": "2",\
>       "params": {\
>         "to\_offset": "10h",\
>         "count": "5"\
>       }\
>     }\
>   ]\
> }\
> \`\`\`\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Batch request example with path parameters\
> \
> \
> Assuming that \`some\_operation\_id\` corresponds to an endpoint\
> that contains the \`id\` path parameter. To call this action and\
> specify the value \`2\` for the \`id\` path parameter we would do\
> the following.\
> \
> \`\`\`json\
> {\
>   "requests": \[\
>     {\
>       "operation\_id": "some\_operation\_id",\
>       "name": "1",\
>       "path\_params": {\
>         "id": "2"\
>       }\
>     }\
>   ]\
> }\
> \`\`\`\
> \
> {% endhint %}\
> \
> \
> \## Response format\
> \
> The status code on a batch response is typically \`200\` or \`400\`.\
> \
> {% hint style="warning" %}\
> \
> \## Malformed batch request\
> \
> \
> A \`400\` status code indicates that the batch request contains an invalid\
> format or semantic errors are present. Some of these errors may be\
> an invalid \`operation\_id\` or individual request \`names\` not being unique.\
> \
> {% endhint %}\
> \
> \
> {% hint style="success" %}\
> \
> \## Valid batch requests\
> \
> \
> A \`200\` status code indicates that the batch request is in the correct format.\
> In that case, \`data\` property will contain the list of responses. For each\
> response, the following properties will be returned:\
> \
> \- \`body\`: The body of the response. It will contain the data or the errors\
> or the individual request. Refer to the corresponding endpoint documentation\
> for the available response format of each request.\
> \- \`name\`: The unique \`name\` of the request this response corresponds to.\
> \- \`status\_code\`: The \`status code\` of the individual request.\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Individual responses\
> \
> \
> A \`200\` status code on the batch response does not indicate that the individual\
> requests inside the batch succeeded. This is why each individual response has\
> a status code as well.\
> \
> {% endhint %}\
> \
> \
> {% hint style="info" %}\
> \
> \## Batch response example\
> \
> \
> \`\`\`\
> {\
>   "data": \[\
>     {\
>       "body": {\
>         "data": \[\
>           {\
>             "begin": "2021-11-24T20:00:00Z",\
>             "country": "EUR",\
>             "country\_id": null,\
>             "event\_id": "SBTE\_25177302",\
>             "league": "Champions League",\
>             "league\_id": "SBTC3\_40685",\
>             "participant\_ids": \[\
>               "SBTP\_246",\
>               "SBTP\_258"\
>             ],\
>             "participants": \[\
>               "Liverpool",\
>               "Porto"\
>             ],\
>             "sport": "Football",\
>             "sport\_id": "SBTC1\_1",\
>             "status": "ended",\
>             "total\_bets": 11439\
>           },\
>           ...\
>         ],\
>         "status": "success"\
>       },\
>       "name": "1",\
>       "status\_code": 200\
>     },\
>     {\
>       "body": {\
>         "data": \[\
>           {\
>             "begin": "2021-11-25T19:30:00Z",\
>             "country": "EUR",\
>             "country\_id": null,\
>             "event\_id": "SBTE\_25425284",\
>             "league": "Euroleague",\
>             "league\_id": "SBTC3\_42161",\
>             "participant\_ids": \[\
>               "SBTP\_377739",\
>               "SBTP\_643"\
>             ],\
>             "participants": \[\
>               "Baskonia",\
>               "Real Madrid"\
>             ],\
>             "score": 12.7832,\
>             "sport": "Basketball",\
>             "sport\_id": "SBTC1\_2",\
>             "status": "ended"\
>           },\
>           ...\
>         ],\
>         "status": "success"\
>       },\
>       "name": "2",\
>       "status\_code": 200\
>     }\
>   ],\
>   "status": "success"\
> }\
> \`\`\`\
> \
> {% endhint %}\ <br>

````json
{"openapi":"3.0.1","info":{"title":"","version":"0.1.0"},"tags":[{"description":"Issue multiple API requests at once","name":"Batch Requests"}],"servers":[{"description":"Production API","url":"https://api.vaix.ai"},{"description":"Staging (integration) API","url":"https://staging-api.vaix.ai"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"scheme":"bearer","type":"http"}},"schemas":{"BatchRequest":{"description":"The list of requests to serve","type":"array","items":{"$ref":"#/components/schemas/Request"}},"Request":{"description":"A request object","type":"object","properties":{"body_params":{"description":"The body params of the request","type":"object"},"name":{"description":"A unique name identifying the request","type":"string"},"operation_id":{"description":"The id of the operation to execute, e.g. get_popular_events","type":"string"},"params":{"description":"The query params of the request","type":"object"},"path_params":{"description":"The path params of the request","type":"object"}},"additionalProperties":false},"Response":{"description":"A response object","type":"object","properties":{"body":{"description":"The response body. It will contain the returned data or the errors occured. For 204 statuses it will be null","type":"object","nullable":true},"name":{"description":"The name identifying the request that the response corresponds","type":"string"},"status_code":{"description":"The status code of the response","type":"integer"}},"additionalProperties":false},"Error":{"description":"The generic API's error response","type":"object","properties":{"error":{"description":"Description of the error","type":"string"},"status":{"description":"response status","type":"string"}},"additionalProperties":false},"Errors":{"description":"The generic API's errors response","type":"object","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"additionalProperties":false},"UnprocessableEntityError":{"oneOf":[{"additionalProperties":false,"description":"The generic API's error response","properties":{"error":{"description":"Description of the error","type":"string"},"status":{"description":"response status","type":"string"}},"type":"object"},{"additionalProperties":false,"description":"The generic API's errors response","properties":{"errors":{"description":"An object with the request errors","type":"object"}},"type":"object"}]}}},"paths":{"/api/batch":{"post":{"operationId":"create_batch_request","summary":"Issue a batch request","description":"Combine multiple requests in a single batch and return a consolidated response.\n\n## Request format\n\nBatch requests are always issued as `POST` requests.\n\nA batch request body consists of a single JSON object with one required\nproperty: `requests`. The `requests` property is an array containing the\nindividual requests. For each of these requests, the following properties\nare supported:\n\n- `operation_id`: **Required** The unique operation_id corresponding to the endpoint action\n- `name`: **Required** A name to associate individual responses with requests.\nIn each batch, all requests should have unique names.\n- `params`: **Optional** An object containing the query params of the request, if any.\n- `body_params`: **Optional** An object containing the body params of the request, if any.\n- `path_params`: **Optional** An object containing the path parameters, if any.\nSince we use the `operation_id` to identify the endpoint to call, this property\nis needed for endpoints containing path parameters. This is used for internal cases mostly.\nSee below for an example of this case.\n\n\n{% hint style=\"info\" %}\n\n## Batch request example\n\n\nIn the following example, we will fetch both popular and trending events\nin a single request.\n\n```json\n{\n  \"requests\": [\n    {\n      \"operation_id\": \"get_popular_events\",\n      \"name\": \"1\",\n      \"params\": {\n        \"count\": \"10\",\n        \"filters\": \"sport:eq:Soccer\"\n      }\n    },\n    {\n      \"operation_id\": \"get_trending_events\",\n      \"name\": \"2\",\n      \"params\": {\n        \"to_offset\": \"10h\",\n        \"count\": \"5\"\n      }\n    }\n  ]\n}\n```\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Batch request example with path parameters\n\n\nAssuming that `some_operation_id` corresponds to an endpoint\nthat contains the `id` path parameter. To call this action and\nspecify the value `2` for the `id` path parameter we would do\nthe following.\n\n```json\n{\n  \"requests\": [\n    {\n      \"operation_id\": \"some_operation_id\",\n      \"name\": \"1\",\n      \"path_params\": {\n        \"id\": \"2\"\n      }\n    }\n  ]\n}\n```\n\n{% endhint %}\n\n\n## Response format\n\nThe status code on a batch response is typically `200` or `400`.\n\n{% hint style=\"warning\" %}\n\n## Malformed batch request\n\n\nA `400` status code indicates that the batch request contains an invalid\nformat or semantic errors are present. Some of these errors may be\nan invalid `operation_id` or individual request `names` not being unique.\n\n{% endhint %}\n\n\n{% hint style=\"success\" %}\n\n## Valid batch requests\n\n\nA `200` status code indicates that the batch request is in the correct format.\nIn that case, `data` property will contain the list of responses. For each\nresponse, the following properties will be returned:\n\n- `body`: The body of the response. It will contain the data or the errors\nor the individual request. Refer to the corresponding endpoint documentation\nfor the available response format of each request.\n- `name`: The unique `name` of the request this response corresponds to.\n- `status_code`: The `status code` of the individual request.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Individual responses\n\n\nA `200` status code on the batch response does not indicate that the individual\nrequests inside the batch succeeded. This is why each individual response has\na status code as well.\n\n{% endhint %}\n\n\n{% hint style=\"info\" %}\n\n## Batch response example\n\n\n```\n{\n  \"data\": [\n    {\n      \"body\": {\n        \"data\": [\n          {\n            \"begin\": \"2021-11-24T20:00:00Z\",\n            \"country\": \"EUR\",\n            \"country_id\": null,\n            \"event_id\": \"SBTE_25177302\",\n            \"league\": \"Champions League\",\n            \"league_id\": \"SBTC3_40685\",\n            \"participant_ids\": [\n              \"SBTP_246\",\n              \"SBTP_258\"\n            ],\n            \"participants\": [\n              \"Liverpool\",\n              \"Porto\"\n            ],\n            \"sport\": \"Football\",\n            \"sport_id\": \"SBTC1_1\",\n            \"status\": \"ended\",\n            \"total_bets\": 11439\n          },\n          ...\n        ],\n        \"status\": \"success\"\n      },\n      \"name\": \"1\",\n      \"status_code\": 200\n    },\n    {\n      \"body\": {\n        \"data\": [\n          {\n            \"begin\": \"2021-11-25T19:30:00Z\",\n            \"country\": \"EUR\",\n            \"country_id\": null,\n            \"event_id\": \"SBTE_25425284\",\n            \"league\": \"Euroleague\",\n            \"league_id\": \"SBTC3_42161\",\n            \"participant_ids\": [\n              \"SBTP_377739\",\n              \"SBTP_643\"\n            ],\n            \"participants\": [\n              \"Baskonia\",\n              \"Real Madrid\"\n            ],\n            \"score\": 12.7832,\n            \"sport\": \"Basketball\",\n            \"sport_id\": \"SBTC1_2\",\n            \"status\": \"ended\"\n          },\n          ...\n        ],\n        \"status\": \"success\"\n      },\n      \"name\": \"2\",\n      \"status_code\": 200\n    }\n  ],\n  \"status\": \"success\"\n}\n```\n\n{% endhint %}\n\n","parameters":[{"name":"x-vaix-client-id","in":"header","description":"Custom client header, the value should be the name of the group the user belongs to","required":true,"schema":{"type":"string"}},{"name":"x-vaix-authentication-method","in":"header","description":"Authentication method to be used, supported values [`vaix`, `iam`]. Defaults to `vaix`","required":false,"schema":{"type":"string"}}],"requestBody":{"description":"The requests to serve","content":{"application/json":{"schema":{"description":"API response","type":"object","properties":{"requests":{"$ref":"#/components/schemas/BatchRequest"}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"description":"API response","type":"object","properties":{"data":{"description":"Array of objects","type":"array","items":{"$ref":"#/components/schemas/Response"}},"status":{"description":"The status of the request","type":"string","enum":["success","error"]}},"additionalProperties":false}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"406":{"description":"Not Acceptable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}}},"413":{"description":"Request Entity Too Large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnprocessableEntityError"}}}},"425":{"description":"Too Early","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Errors"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["Batch Requests"]}}}}
````


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.sportradar.com/personalization/api-reference/utilities/batch-requests.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.