{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":474,"path":"api-reference/rest-apis/batch-api.md","title":"Batch API","bundle":null,"doc_type":null,"release":"australia","body":"\n# Batch API\n\nThe Batch API provides endpoints to send a single request containing multiple REST API calls, and returns a stream of response payloads.\n\nThis REST API enables integrators to:\n\n-   Decrease the amount of time required to send API requests by batching them together, and reduce overhead by narrowing authentication, session setup, and round-trip traffic to a single step.\n-   Create more efficient code for client-side integrations.\n-   Mix batch item formats and include them in single batch request. For example, one batch can include a Bases64-encoded request in XML format to send to one endpoint and a Base64 encoded request in JSON format to send to a different endpoint.\n-   Receive a stream of response payloads in return.\n-   Apply existing ACLs to each API call in the batch.\n\nYou can include any API available on the instance in a Batch API call. For performance reasons, avoid including long-running requests and requests that retrieve large amounts of data.\n\n**Important:** The Batch API has the same performance characteristics as individual API requests but avoids the overhead of multiple client-server requests. The Batch API is not intended for parallel transaction processing and long-running API requests may cause the API request to exceed the maximum transaction time and return a failure.\n\n## Size and processing limits\n\nPayloads adhere to these size limits:\n\n-   Each item in the request: 5 MB​. You can change this default by updating the **glide.rest.batch.max.inputSize​** system property. Maximum value: 10 MB.\n-   Each item in the response: 10 MB. You can change this default by updating the **glide.rest.batch.max.outputSize​** system property or adding the **X-BATCHREQUEST-MAX-OUTPUT-SIZE​** header to your request. The **X-BATCHREQUEST-MAX-OUTPUT-SIZE​** header value cannot exceed the value of the system property.\n\n**Note:** If a request runs longer than 30 seconds, the **REST Batch API request timeout** transaction quota rule ends the transaction. Increasing the value of this transaction quota rule may result in performance issues.\n\nWhen a batch request reaches a size or processing limit, the system cancels the transaction and returns unprocessed requests in the **unserviced** JSON array in the response.\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## Batch - POST /now/batch\n\nSends multiple REST API requests in a single call.\n\nYou can include any API available on the instance in a Batch API call. For performance reasons, avoid including long-running requests and requests that retrieve large amounts of data.\n\n### URL format\n\nVersioned URL: `/api/now/{api_version}/batch`\n\n### Supported request parameters\n\n<table class=\"rest_api_path_parameters\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\napi\\_version\n\n</td><td>\n\nVersion of the endpoint to access. For example, `v1` or `v2`.Data type: String\n\n</td></tr></tbody>\n</table>|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nbatch\\_request\\_id\n\n</td><td>\n\nID that identifies the batch of requests.Data type: String\n\n</td></tr><tr><td>\n\nrest\\_requests\n\n</td><td>\n\nRequired. List of request objects to include in the batch request. Data type: Array\n\n ```\n\"rest_requests\":[\n   {\n      \"body\": \"String\",\n      \"exclude_response_headers\": Boolean,\n      \"headers\":[Array],\n      \"id\": \"String\",\n      \"method\": \"String\",\n      \"url\": \"String\"\n   }\n]\n```\n\n</td></tr><tr><td>\n\nrest\\_requests.body\n\n</td><td>\n\nBase64-encoded body of the request. Only applies to methods that require a body, for example POST. Before encoding, the body can be in any format. For example, XML or JSON. Data type: String\n\n</td></tr><tr><td>\n\nrest\\_requests.exclude\\_response\\_headers\n\n</td><td>\n\nFlag that indicates whether to exclude response headers from the response.Valid values:\n\n-   true: Response headers are not included in the response.\n-   false: Response headers are included in the response.\n\n Data type: Boolean\n\n Default: false\n\n</td></tr><tr><td>\n\nrest\\_requests.headers\n\n</td><td>\n\nList of request header objects to send to the endpoint.Data type: Array\n\n ```\n\"headers\":[\n  {\n    \"name\":\"String\",\n    \"value\":\"String\"\n  }\n]\n```\n\n</td></tr><tr><td>\n\nrest\\_requests.headers.name\n\n</td><td>\n\nName of the header.Data type: String\n\n</td></tr><tr><td>\n\nrest\\_requests.headers.value\n\n</td><td>\n\nValue of the header.Data type: String\n\n</td></tr><tr><td>\n\nrest\\_requests.id\n\n</td><td>\n\nRequired. ID for each item in the batch.Data type: String\n\n</td></tr><tr><td>\n\nrest\\_requests.method\n\n</td><td>\n\nRequired. Method to call for the associated endpoint.Data type: String\n\n</td></tr><tr><td>\n\nrest\\_requests.url\n\n</td><td>\n\nRequired. Relative path of the endpoint to send the request to. Includes the query parameters. Data type: String\n\n</td></tr></tbody>\n</table>### Headers\n\nThe following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see [Supported REST API headers](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td>\n\nData format of the response body. Supported types: **application/json** or **multipart/mixed**.To stream multipart responses, set the **glide.rest.serialize.disable\\_response\\_stream\\_buffering** system property to true. For more information, see [Available system properties](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-administration/r_AvailableSystemProperties.md).\n\n</td></tr><tr><td>\n\nContent-Type\n\n</td><td>\n\nData format of the request body. Only supports **application/json**.\n\n</td></tr><tr><td>\n\nX-BATCHREQUEST-MAX-OUTPUT-SIZE​\n\n</td><td>\n\nSize limit for each item in the batch response. Add this header to provide a lower size limit than the default set by the ​**glide.rest.batch.max.outputSize​** system property. You cannot set a value higher than the value in the system property. Default: 10 MB.\n\n</td></tr></tbody>\n</table>|Header|Description|\n|------|-----------|\n|None| |\n\n### Status codes\n\nThe following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see [REST API HTTP response codes](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n|Status code|Description|\n|-----------|-----------|\n|200|Successful. The request was successfully processed.|\n|401|Unauthorized. The user credentials are incorrect or have not been passed.|\n|500|Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.|\n\n### Response body parameters \\(JSON\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nbatch\\_request\\_id\n\n</td><td>\n\nID of the batch that matches the **batch\\_request\\_id** parameter in the request.Data type: String\n\n</td></tr><tr><td>\n\nserviced\\_requests\n\n</td><td>\n\nList of response objects from the batch request. Data type: Array\n\n ```\n\"serviced_requests\":[\n  {\n    \"body\": \"String\",\n    \"error_message\": \"String\",\n    \"execution_time\": Number,\n    \"headers\": [Array],\n    \"id\": \"String\",\n    \"redirect_url: \"String\",\n    \"status_code\": Number,\n    \"status_text\": \"String\"\n  }\n]\n```\n\n</td></tr><tr><td>\n\nserviced\\_requests.body\n\n</td><td>\n\nBase64 encoded body of the response. To get the value of the body, Base64 decode the content of this parameter.Data type: String\n\n</td></tr><tr><td>\n\nserviced\\_requests.error\\_message\n\n</td><td>\n\nIf present, the error messages.Data type: String\n\n</td></tr><tr><td>\n\nserviced\\_requests.execution\\_time\n\n</td><td>\n\nTime it took to execute the batch item request.Data type: Number\n\n Unit: Milliseconds\n\n</td></tr><tr><td>\n\nserviced\\_requests.headers\n\n</td><td>\n\nHeaders for the batch item.Data type: Array\n\n ```\n\"headers\":[\n  {\n    \"name\":\"String\",\n    \"value\":\"String\"\n  }\n]\n```\n\n</td></tr><tr><td>\n\nserviced\\_requests.headers.name\n\n</td><td>\n\nName of the header.Data type: String\n\n</td></tr><tr><td>\n\nserviced\\_requests.headers.value\n\n</td><td>\n\nValue of the header.Data type: String\n\n</td></tr><tr><td>\n\nserviced\\_requests.id\n\n</td><td>\n\nID of the batch item that matches the **rest\\_requests.id** parameter in the request.Data type: String\n\n</td></tr><tr><td>\n\nserviced\\_requests.redirect\\_url\n\n</td><td>\n\nIf present, the redirect URL.Data type: String\n\n</td></tr><tr><td>\n\nserviced\\_requests.status\\_code\n\n</td><td>\n\nStatus code for the batch item.Data type: Number\n\n</td></tr><tr><td>\n\nserviced\\_requests.status\\_text\n\n</td><td>\n\nText of the status code for the batch item.Data type: String\n\n</td></tr><tr><td>\n\nunserviced\\_requests\n\n</td><td>\n\nIDs of the requests that were not processed because the batch request reached a size or processing limit. Data type: Array\n\n</td></tr></tbody>\n</table>### cURL request\n\nThis batch request sends two GET requests to the instance and one POST request to the incident table. The body of the POST request is Base64 encoded.\n\n```\ncurl \"https://instance.servicenow.com/api/now/v1/batch\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--header \"Content-Type:application/json\" \\\n--user \"username\":\"password\"\\\n--data \"{\n   \\\"batch_request_id\\\":\\\"1\\\",\n   \\\"rest_requests\\\":[\n      {\n         \\\"id\\\":\\\"11\\\",\n         \\\"headers\\\":[\n            {\n               \\\"name\\\":\\\"Content-Type\\\",\n               \\\"value\\\":\\\"application/xml\\\"\n            },\n            {\n               \\\"name\\\":\\\"Accept\\\",\n               \\\"value\\\":\\\"application/xml\\\"\n            }\n         ],\n         \\\"url\\\":\\\"/api/global/user_role_inheritance\\\",\n         \\\"method\\\":\\\"GET\\\"\n      },\n      {\n         \\\"id\\\":\\\"12\\\",\n         \\\"exclude_response_headers\\\":true,\n         \\\"headers\\\":[\n            {\n               \\\"name\\\":\\\"Content-Type\\\",\n               \\\"value\\\":\\\"application/json\\\"\n            },\n            {\n               \\\"name\\\":\\\"Accept\\\",\n               \\\"value\\\":\\\"application/json\\\"\n            }\n         ],\n         \\\"url\\\":\\\"/api/now/table/incident?sysparm_limit=1\\\",\n         \\\"method\\\":\\\"GET\\\"\n      },\n      {\n         \\\"id\\\":\\\"13\\\",\n         \\\"exclude_response_headers\\\":true,\n         \\\"headers\\\":[\n            {\n               \\\"name\\\":\\\"Content-Type\\\",\n               \\\"value\\\":\\\"application/json\\\"\n            },\n            {\n               \\\"name\\\":\\\"Accept\\\",\n               \\\"value\\\":\\\"application/json\\\"\n            }\n         ],\n         \\\"url\\\": \\\"/api/now/table/incident\\\",\n         \\\"method\\\":\\\"POST\\\",\n         \\\"body\\\": \\\"eyd1cmdlbmN5JzonMScsICdzaG9ydF9kZXNjcmlwdGlvbic6J015IGNvbXB1dGVyIG\n          Jyb2tlJywgJ2NvbW1lbnRzJzonRWxldmF0aW5nIHVyZ2VuY3ksIHRoaXMgaXMgYSBibG9ja2luZyBpc3N1ZSd9\\\"\n      }\n   ]\n}\" \\\n```\n\n```\n{\n    \"batch_request_id\": \"1\",\n    \"serviced_requests\": [\n        {\n            \"id\": \"11\",\n            \"body\": \"PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cmVzcG9uc2U+PHJlc3VsdD48dX\n            Nlcl9uYW1lLz48L3Jlc3VsdD48L3Jlc3BvbnNlPg==\",\n            \"status_code\": 200,\n            \"status_text\": \"OK\",\n            \"headers\": [\n                {\n                    \"name\": \"Pragma\",\n                    \"value\": \"no-store,no-cache\"\n                },\n                {\n                    \"name\": \"Expires\",\n                    \"value\": \"0\"\n                },\n                {\n                    \"name\": \"Content-Length\",\n                    \"value\": \"88\"\n                },\n                {\n                    \"name\": \"Content-Type\",\n                    \"value\": \"application/xml; charset=UTF-8\"\n                },\n                {\n                    \"name\": \"Cache-control\",\n                    \"value\": \"no-cache,no-store,must-revalidate,max-age=-1\"\n                }\n            ],\n            \"execution_time\": 5\n        },\n        {\n            \"id\": \"12\",\n            \"body\": \"eyJyZXN1bHQiOlt7InBhcmVudCI6IiIsIm1hZGVfc2xhIjoidHJ1ZSIsImNhdXNlZF9\n            ieSI6IiIsIndhdGNoX2xpc3QiOiIiLCJ1cG9uX3JlamVjdCI6ImNhbmNlbCIsInN5c191cGRhdGV\n            kX29uIjoiMjAxNi0xMi0xNCAwMjo0Njo0NCIsImNoaWxkX2luY2lkZW50cyI6IjAiLCJob2xkX3J\n            lYXNvbiI6IiIsInRhc2tfZWZmZWN0aXZlX251bWJlciI6IklOQzAwMDAwNjAiLCJhcHByb3ZhbF9\n            oaXN0b3J5IjoiIiwibnVtYmVyIjoiSU5DMDAwMDA2MCIsInJlc29sdmVkX2J5Ijp7ImxpbmsiOiJ\n            odHRwczovL2s4czAwNjc5Nzgtbm9kZTEudGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGk\n            vbm93L3RhYmxlL3N5c191c2VyLzUxMzcxNTNjYzYxMTIyN2MwMDBiYmQxYmQ4Y2QyMDA3IiwidmF\n            sdWUiOiI1MTM3MTUzY2M2MTEyMjdjMDAwYmJkMWJkOGNkMjAwNyJ9LCJzeXNfdXBkYXRlZF9ieSI\n            6ImVtcGxveWVlIiwib3BlbmVkX2J5Ijp7ImxpbmsiOiJodHRwczovL2s4czAwNjc5Nzgtbm9kZTE\n            udGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGkvbm93L3RhYmxlL3N5c191c2VyLzY4MWN\n            jYWY5YzBhODAxNjQwMGI5OGEwNjgxOGQ1N2M3IiwidmFsdWUiOiI2ODFjY2FmOWMwYTgwMTY0MDB\n            iOThhMDY4MThkNTdjNyJ9LCJ1c2VyX2lucHV0IjoiIiwic3lzX2NyZWF0ZWRfb24iOiIyMDE2LTE\n            yLTEyIDE1OjE5OjU3Iiwic3lzX2RvbWFpbiI6eyJsaW5rIjoiaHR0cHM6Ly9rOHMwMDY3OTc4LW5\n            vZGUxLnRodW5kZXIubGFiMy5zZXJ2aWNlLW5vdy5jb20vYXBpL25vdy90YWJsZS9zeXNfdXNlcl9\n            ncm91cC9nbG9iYWwiLCJ2YWx1ZSI6Imdsb2JhbCJ9LCJzdGF0ZSI6IjciLCJyb3V0ZV9yZWFzb24\n            iOiIiLCJzeXNfY3JlYXRlZF9ieSI6ImVtcGxveWVlIiwia25vd2xlZGdlIjoiZmFsc2UiLCJvcmR\n            lciI6IiIsImNhbGVuZGFyX3N0YyI6IjEwMjE5NyIsImNsb3NlZF9hdCI6IjIwMTYtMTItMTQgMDI\",\n            \"status_code\": 200,\n            \"status_text\": \"OK\",\n            \"headers\": [],\n            \"execution_time\": 8\n        },\n        {\n            \"id\": \"13\",\n            \"body\": \"eyJyZXN1bHQiOnsicGFyZW50IjoiIiwibWFkZV9zbGEiOiJ0cnVlIiwiY2F1c2VkX2J\n            5IjoiIiwid2F0Y2hfbGlzdCI6IiIsInVwb25fcmVqZWN0IjoiY2FuY2VsIiwic3lzX3VwZGF0ZWR\n            fb24iOiIyMDIwLTA1LTEyIDAxOjQ0OjM1IiwiY2hpbGRfaW5jaWRlbnRzIjoiMCIsImhvbGRfcmV\n            hc29uIjoiIiwidGFza19lZmZlY3RpdmVfbnVtYmVyIjoiSU5DMDAxMDAwNCIsImFwcHJvdmFsX2h\n            pc3RvcnkiOiIiLCJudW1iZXIiOiJJTkMwMDEwMDA0IiwicmVzb2x2ZWRfYnkiOiIiLCJzeXNfdXB\n            kYXRlZF9ieSI6ImFkbWluIiwib3BlbmVkX2J5Ijp7ImxpbmsiOiJodHRwczovL2s4czAwNjc5Nzg\n            tbm9kZTEudGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGkvbm93L3RhYmxlL3N5c191c2V\n            yLzY4MTZmNzljYzBhODAxNjQwMWM1YTMzYmUwNGJlNDQxIiwidmFsdWUiOiI2ODE2Zjc5Y2MwYTg\n            wMTY0MDFjNWEzM2JlMDRiZTQ0MSJ9LCJ1c2VyX2lucHV0IjoiIiwic3lzX2NyZWF0ZWRfb24iOiI\n            yMDIwLTA1LTEyIDAxOjQ0OjM1Iiwic3lzX2RvbWFpbiI6eyJsaW5rIjoiaHR0cHM6Ly9rOHMwMDY\n            3OTc4LW5vZGUxLnRodW5kZXIubGFiMy5zZXJ2aWNlLW5vdy5jb20vYXBpL25vdy90YWJsZS9zeXN\n            fdXNlcl9ncm91cC9nbG9iYWwiLCJ2YWx1ZSI6Imdsb2JhbCJ9LCJzdGF0ZSI6IjEiLCJyb3V0ZV9\n            yZWFzb24iOiIiLCJzeXNfY3JlYXRlZF9ieSI6ImFkbWluIiwia25vd2xlZGdlIjoiZmFsc2UiLCJ\",\n            \"status_code\": 201,\n            \"status_text\": \"Created\",\n            \"headers\": [],\n            \"execution_time\": 2638\n        }\n    ],\n    \"unserviced_requests\": []\n}\n```\n\n"}}