Get early access

    Batch requests and idempotency

    Not open yet. Opens with early access.

    On this page

    One call, many decisions

    POST /v1/understand/batch takes { "requests": [ … ] }: 1 to 100 bodies, each a /v1/understand request. It answers { "results": [ … ] } in the same order, each result with the item’s status and body.

    Bash
    curl "$UNDERSTANDING_API_URL/v1/understand/batch" \
  -H "Authorization: Bearer $UNDERSTANDING_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "requests": [
      {
        "decision": "restricted_merchant",
        "input": { "merchant": "DRAFTKINGS", "mcc": "7995" }
      },
      { "decision": "spend_type", "input": { "mcc": "5411" } }
    ]
  }'
    Response

    200 OKStand-in probability1

    {
  "results": [
    {
      "status": 200,
      "body": {
        "decision": "restricted_merchant",
        "type": "predicate",
        "answer": true,
        "probability": 0.97,
        "reasons": [
          "mcc_7995",
          "rule_gambling_category",
          "kind_sportsbook"
        ],
        "abstain": false
      }
    },
    {
      "status": 200,
      "body": {
        "decision": "spend_type",
        "type": "choice",
        "answer": "essential",
        "probability": 0.97,
        "reasons": ["mcc_5411"],
        "abstain": false
      }
    }
  ]
}

    How the items run

    • Eight at a time, answered in the order you sent them.
    • The key is checked once for the batch. Then each item is checked for credit, rate and sensitive data, and for its fields, like a single call.
    • A bad item gets its own 400, and an item over the rate limit its own 429. Neither fails the batch.
    • Items count toward the key’s 60 requests a minute, so a batch larger than what’s left of the minute comes back partly as 429s. Send those again after the wait.
    • Each item costs what the same single call costs. Items carry no cost headers: read GET /v1/usage for totals.

    Batch errors

    Errors for the whole batch
    StatusMessageWhen
    413The body is over 1 MB.The batch body is over 1 MB.
    400The body must be JSON.The body didn’t parse.
    400requests must be an array of 1 to 100 understand requestsrequests is missing, empty or too long. field: "requests".
    401As for a single callNo credential, or one that isn’t valid.

    Idempotency

    Send an Idempotency-Key header, the same on every try of one request. If the first try succeeded and only its response was lost, the retry gets that response back, with idempotent-replayed: true, and no second model call or charge. One key covers a whole batch.

    • The key is 1 to 255 printable characters; a UUID works.
    • It holds for 24 hours, per account.
    • Only a success is kept. After an error, a retry with the same key runs again.
    • The same key with a different body is a 422. While the first request still runs, a 409 with Retry-After: 1.

    Handle errors and retries