Log Up to 100 Audit Events — POST /v1/events/batch

The /v1/events/batch endpoint lets you record up to 100 audit events in a single API call. Batching is the recommended pattern for high-throughput services — it reduces round-trip overhead, and the entire batch counts as just one request against your rate limit. Each event in the array follows the same structure as a single event: an action is required, while actor_id, resource, and metadata are optional. If you only need to record one event at a time, see the single event endpoint instead.

Request

POST https://api.auditrails.io/v1/events/batch

Headers

string

required

Your AuditRails API key, prefixed with Bearer. Use a live key (at_live_xxx) for production traffic and a test key (at_test_xxx) for development.Example: Bearer at_live_xxx

string

required

Must be application/json.

string

An optional client-generated string (e.g. a UUID) that makes the entire batch safe to retry. If you resend the same key with an identical request body, AuditRails replays the original 202 response and sets the Idempotency-Replayed: true response header — no duplicate events are written.Sending the same key with a different body returns a 409 conflict error. Keys are retained for 24 hours.

Body

array

required

An array of event objects to log. Must contain between 1 and 100 events. The batch is processed atomically — if any single event fails validation, the entire batch is rejected and nothing is written. Correct all validation errors and resubmit the full batch.Each event object supports the following fields:

Show Event object fields

string

required

A string identifying what happened. Maximum 255 characters. Must match an entry in your compliance catalog or be a registered custom action. We strongly recommend the resource.verb format (e.g. user.login, document.created, permission.granted).

string

The identifier of the person or system that performed the action. Maximum 255 characters. Omit only when the actor is genuinely unknown or not applicable.

string

The object the action was performed on. Maximum 255 characters. Use the type/id format (e.g. document/doc-456) so that resource-scoped queries work correctly in the AuditRails dashboard.

object

A free-form key-value object for any additional context. There is no hard limit on the number of keys, but the total request body must not exceed 2 MB.

Example request

curl -X POST https://api.auditrails.io/v1/events/batch \
  -H "Authorization: Bearer at_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "action": "user.login",
        "actor_id": "user_123",
        "resource": "session/sess_abc",
        "metadata": { "ip": "203.0.113.1" }
      },
      {
        "action": "document.created",
        "actor_id": "user_123",
        "resource": "document/doc-456",
        "metadata": { "title": "Q4 Report" }
      },
      {
        "action": "permission.granted",
        "actor_id": "user_123",
        "resource": "document/doc-456",
        "metadata": { "grantee": "user_789", "role": "viewer" }
      }
    ]
  }'

{
  "events": [
    {
      "action": "user.login",
      "actor_id": "user_123",
      "resource": "session/sess_abc",
      "metadata": { "ip": "203.0.113.1" }
    },
    {
      "action": "document.created",
      "actor_id": "user_123",
      "resource": "document/doc-456",
      "metadata": { "title": "Q4 Report" }
    },
    {
      "action": "permission.granted",
      "actor_id": "user_123",
      "resource": "document/doc-456",
      "metadata": { "grantee": "user_789", "role": "viewer" }
    }
  ]
}

Atomic writes: The batch endpoint writes all events or none. If any event in the array fails validation — for example, a missing action field — the entire batch is rejected with a 422 error that identifies the offending index (e.g. event[2]: action field required). Correct every flagged event and resubmit the complete array.

Rate limiting: Regardless of how many events are in the array, the batch endpoint counts as a single request against your rate limit. Batching is the most efficient way to ingest high volumes of events without hitting rate limits.

Response

A 202 Accepted response means all events in the batch have been durably written and sealed.

202 Accepted

array of strings

An ordered array of unique, immutable identifiers for each accepted audit log entry. The IDs are returned in the same order as the events in your request array, so log_ids[0] corresponds to events[0], log_ids[1] to events[1], and so on. Each ID is a ULID — lexicographically sortable and time-prefixed.

string

A unique identifier for the API request itself. Include this value in any support tickets or bug reports related to this call.

Example response

{
  "log_ids": [
    "01HX7YGBFZ3QK8N9VMJT5RPCE4",
    "01HX7YGBFZ3QK8N9VMJT5RPCE5",
    "01HX7YGBFZ3QK8N9VMJT5RPCE6"
  ],
  "request_id": "req_01HX7YH5KP2RMWT6AJCD8BXEN7"
}

Error responses

HTTP Status	Error Code	Description
`400`	`validation/batch_empty`	The `events` array is present but contains zero items. Include at least one event object.
`400`	`validation/batch_too_large`	The `events` array exceeds the 100-event maximum. Split your payload into smaller batches and resubmit.
`401`	`auth/key_not_found`	The API key in the `Authorization` header was not recognized. Check that you are using the correct key for the target environment.
`409`	`event/idempotency_key_conflict`	An `Idempotency-Key` was reused with a different request body. Use a new key or resend the original body.
`422`	`validation/missing_action`	One or more events are missing the required `action` field. The error message identifies the first offending index (e.g. `event[2]: action field required`). Fix all invalid events and resubmit the full batch.

Because the batch is all-or-nothing, a single invalid event blocks the entire array from being written. The 422 error message will tell you which index is invalid, but make sure to audit all events in your batch before resubmitting — there may be multiple validation errors beyond the first one reported.

Overview

Ingestion

Read & Verify

Data Subject Requests

Log Up to 100 Audit Events — POST /v1/events/batch

Request

Headers

Body

Example request

Response

202 Accepted

Example response

Error responses

​Request

​Headers

​Body

​Example request

​Response

​202 Accepted

​Example response

​Error responses

Request

Headers

Body

Example request

Response

202 Accepted

Example response

Error responses