Skip to main content

Batch Query API

The batch query API exposes an endpoint for executing multiple policy evaluations in a single request.

Batch Querying a Policy

POST /v1/batch/data/{path:.+}
Content-Type: application/json

This batch query endpoint behaves similar to OPA's Data API – Get a Document (with Input).

Request Body

KeyTypeDescription
inputsobject[string:any]The inputs object is a map of the inputs for each individual query in the batch. The keys are arbitrary IDs representing each request, and the value is the JSON input object for that request

Query Parameters

All supported parameters are booleans and default to false. These parameters come from the Open Policy Agent Data API.

Open Policy Agent parameters

ParameterDescription
prettyFormat the JSON return with whitespace.
provenanceInclude provenance data in the return object.
metricsInclude basic metrics data in the return object.
instrumentInclude extended metrics in the return object for more in depth debugging (overrides ‘metrics’).
strict-builtin-errorsReturn an error in the event a built-in function errors rather than evaluating to undefined.

Request Headers

NameRequiredAccepted ValuesDescription
Content-TypeYesapplication/json

application/x-yaml
Indicates the request body is either a JSON or YAML encoded document.
Content-EncodingNogzipIndicates the request body is a compressed gzip object.

Status Codes

CodeReason
200Each batched query returned a 200
207The batched queries returned a mix of other codes
400Client side error, e.g. malformed input
500Each batched query returned a 500

The server returns 400 if the input document is invalid (i.e. malformed JSON).

The server returns 200 if the path refers to an undefined document. In this case, the response will contain an empty body.

Response Message

200 Response

KeyTypeDescription
batch_decision_idstringIf decision logging is enabled, this field contains a unique string identifier representing the entire batch of responses.
metricsobject[string:object]If query metrics are enabled, this field contains query performance metrics of the batch request.
responsesobject[string:object]An object containing individual responses keyed with the same key as in the request.
responses[_].decision_idstringIf decision logging is enabled, this field contains a unique string identifier representing the individual response.
responses[_].resultanyThe result of evaluating the policy with the given input.
responses[_].metricsobject[string:object]If query metrics are enabled, this field contains query performance metrics collected during the parse, compile, and evaluation steps.
responses[_].provenanceobject[string:object]If provenance support is enabled, this field contains information about the Enterprise OPA instance, as well as any bundles that have been loaded.

400 Response

A 400 response represents a client side error.

See OPA documentation for information about each of these keys.

KeyType
codestring
messagestring
errorslist[object]
errors[].codestring
errors[].messagestring
errors[].locationobject[string:string]
errors[].location.filestring
errors[].location.rownumber
errors[].location.columnnumber

500 Response

A 500 response represents a server side error for all policy evaluations.

See OPA documentation for information about each of these keys.

KeyTypeDescription
batch_decision_idstringIf decision logging is enabled, this field contains a unique string identifier representing the entire batch of responses.
responses[_].decision_idstringIf decision logging is enabled, this field contains a unique string identifier representing the individual response.
responses[_].codestring
responses[_].messagestring
responses[_].errorslist[object]
responses[_].errors[].codestring
responses[_].errors[].messagestring
responses[_].errors[].locationobject[string:string]
responses[_].errors[].location.filestring
responses[_].errors[].location.rownumber
responses[_].errors[].location.columnnumber

207 Response

Each value in the responses field contains an HTTP status code representing the result of each query. The rest of the fields in the result correspond to the same fields as in the pure 200 or 500 cases.

KeyTypeDescription
responses[_].http_status_codestringThis key contains the HTTP Status Code for the individual response.
metricsobject[string:object]If query metrics are enabled, this field contains query performance metrics of the batch request.

Examples

Successful Evaluations

Using the policy

package app.abac

import rego.v1

default allow := false

allow if input.user.title == "owner"
allow if input.user.tenure > 10
Request
POST /v1/batch/data/app/abac/allow
Content-Type: application/json

{
"inputs": {
"1": {
"user": {"name": "bob", "title": "owner", "tenure": 20},
"action": "read",
"resource": "dog123"
},
"2": {
"user": {"name": "alice", "title": "manager", "tenure": 15},
"action": "read",
"resource": "dog123"
},
"3": {
"user": {"name": "charlie", "title": "worker", "tenure": 5},
"action": "read",
"resource": "dog123"
}
}
}
Response
HTTP/1.1 200 OK
Content-Type: application/json

{
"responses": {
"1": {
"result": true
},
"2": {
"result": true
},
"3": {
"result": false
}
}
}

Mixed Status Response with Decision Logging Enabled and Metrics

Using the policy

package app.abac

import rego.v1

default allow := false

allow if input.user.title == "owner"
allow if input.user.tenure > 10

allow := false if input.user.title == "owner"
Request
POST /v1/batch/data/app/abac/allow?metrics=true
Content-Type: application/json

{
"inputs": {
"1": {
"user": {"name": "bob", "title": "owner", "tenure": 20},
"action": "read",
"resource": "dog123"
},
"2": {
"user": {"name": "alice", "title": "employee"},
"resource": "dog123"
}
}
}
Response
HTTP/1.1 207 Mixed-Status
Content-Type: application/json

{
"batch_decision_id": "08bf7b03-b559-4789-bab7-3c6254fb986a",
"metrics": {
"counter_server_query_cache_hit": 0,
"timer_rego_input_parse_ns": 188541,
"timer_server_handler_ns": 2317250
},
"responses": {
"1": {
"code": "internal_error",
"message": "eval_conflict_error: complete rules must not produce multiple outputs",
"decision_id": "41950d4f-20ad-4439-b0cd-dcb067d1e373",
"http_status_code": "500"
},
"2": {
"decision_id": "16ba30f4-b275-47df-b92a-99e4d17cfb13",
"metrics": {
"counter_regovm_eval_instructions": 23,
"counter_regovm_virtual_cache_hits": 0,
"counter_regovm_virtual_cache_misses": 1,
"counter_server_query_cache_hit": 1,
"timer_regovm_eval_ns": 340500,
"timer_server_handler_ns": 649750
},
"result": false,
"http_status_code": "200"
}
}
}