Skip to main content
POST /v1/key_usage/batches records a batch of requests made with API keys that your account creation gate issued to your accounts. It needs the assess scope. The Node and Python SDKs buffer usage and call it for you. Report key usage explains the buffer, sampling and the shared_api_key rule.

The request

TypeScript
A batch holds 1 to 500 events in events. The body is at most 256 KiB. A larger body answers 413 payload_too_large.

Event fields

string
required
The SHA-256 of the UTF-8 bytes of the issued key, as 64 lower-case hex characters. It is the value that the assessment of the account sent as issued_credential.sha256.
string
required
The client IP address of the request, IPv4 or IPv6, as your server saw it. At most 64 characters.
string
required
When the request occurred, as RFC 3339.
string
The User-Agent of the request, at most 512 characters, with no control characters.
string
The model or product that the request used. At most 128 characters from letters, digits and ., _, :, /, @, +, -.
integer
A whole number from 0 to 1,000,000,000.
integer
A whole number from 0 to 1,000,000,000.
number
default:"1"
More than 0 and at most 1. The share of requests that your sampler records. For example, 0.1 means that the event stands for 10 requests in the request and token totals.

What NoResponse refuses and ignores

NoResponse answers 400 invalid_request in these cases:
  • An unknown member, such as tenant_id.
  • A raw key in key_sha256.
NoResponse does not refuse an event in these cases. It counts the event in ignored, and the event adds nothing:
  • The ip is private, reserved or unreadable.
  • The occurred_at is more than 24 hours old, or more than 5 minutes in the future.

Idempotency

The Idempotency-Key is required. It works as it does on POST /v1/assessments, for 24 hours:
  • The same key and body answers the same record with Idempotent-Replayed: true, and it counts nothing again.
  • The same key with a different body answers 409 idempotency_key_reused.
Use a new key for each batch.

The answer

The answer is 202 with the recorded batch.
string
The id of the batch.
string
When NoResponse got the batch.
integer
The events that NoResponse added to the usage of the key.
integer
The events that added nothing.
Batch response
There is nothing to poll after the answer. When a key goes over the limit, the next read of each account that got the key carries shared_api_key in risk.reasons. See Reason codes.