POST/audit_logs/ledgers
Create a ledger
Creates a ledger and signs its empty checkpoint. Every event in the ledger shares its expiry, so a late event gets the time that remains. Costs one work unit and 1 MiB of retention for each day: $0.002048576 for 30 days. Credentials: a secret key.
| Parameter | Location | Description |
|---|---|---|
| Idempotency-Key | header | 1 to 128 printable ASCII characters: a new value for each operation, and the same value when you retry it. A retry with the same credential replays the first response for 35 days. |
| Motor-Mode | header | Audit logs is live-only: omit it or send live. |
{
"name": "Agent actions",
"retention_days": 30,
"metadata": {
"team": "payments"
},
"max_cost_usd": "0.01"
}| Field | Type | Description |
|---|---|---|
namerequired | string | 1 to 128 UTF-8 bytes. It never changes. |
retention_days | integer | 1 to 365, 30 by default. Every event in the ledger shares its expiry. |
metadata | object | At most 16 string pairs: keys of 1 to 64 UTF-8 bytes, values of at most 256, and at most 2 KiB in all. Metadata never changes. |
max_cost_usd | string | The most that the creation may cost, such as "0.01". |
Responses
201The ledger.
{
"id": "ald_LrB528wYtd4M8VJwtZikAt",
"object": "audit_ledger",
"state": "open",
"created_at": "2026-10-18T09:00:00.000000Z",
"expires_at": "2026-11-17T09:00:00.000000Z",
"remaining_seconds": "2592000",
"remaining_days": "30",
"revision": "1",
"etag": "ald_LrB528wYtd4M8VJwtZikAt:1",
"deletion": null,
"name": "Agent actions",
"metadata": {
"team": "payments"
},
"retention_days": "30",
"sealed_at": null,
"tree_size": "0",
"root_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"checkpoint": {
"tree_size": "0",
"root_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"issued_at": "2026-10-18T09:00:00.000000Z",
"key_id": "development-1",
"algorithm": "ecdsa-p256-sha256",
"signed_body": "{\"issued_at\":\"2026-10-18T09:00:00.000000Z\",\"key_id\":\"development-1\",\"ledger_id\":\"ald_LrB528wYtd4M8VJwtZikAt\",\"root_hash\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"tree_size\":\"0\",\"version\":\"motor-audit-checkpoint-v1\"}",
"signature": "RDCKx2NJ7m1EHKF3RDihL62etRo_98qTbLcv5tOuNOzCc5GEKHA0mtcGUkA-zcq9ahIkND10RQg8Vkti0FveGA"
},
"events": "0",
"billable_bytes": "1048576",
"paid_through": "2026-11-17T09:00:00.000000Z",
"erasure_generation": "0",
"retained_artifacts": 0,
"controls": {
"used": 0,
"remaining": 256
},
"bounds": {
"max_event_bytes": 4096,
"max_batch_events": 100,
"max_targets": 8,
"max_evidence": 8,
"max_page_items": 100,
"max_page_bytes": 131072,
"max_candidates_per_page": "1000",
"max_extension_horizon_days": "365",
"max_controls": 256,
"max_retained_artifacts": 100
},
"cost": {
"rate_version": "2026-10-18",
"charged_usd": "0.002048576"
},
"usage": {
"rate_version": "2026-10-18",
"work_units": "1",
"new_events": "0",
"retained_byte_days": "31457280",
"charged_usd": "0.002048576"
}
}400The body isn't a JSON object, or an Idempotency-Key is missing.
{
"error": {
"code": "invalid_json",
"message": "The request body isn't valid JSON. Expected a JSON value at byte 0.",
"retryable": false
}
}401The key or the client token is missing, invalid, expired, or revoked.
{
"error": {
"code": "unauthorized",
"message": "This API key is invalid or has been revoked.",
"retryable": false
}
}402The team doesn't have a payment card, the key or the token reached its spending limit, or the work would pass max_cost_usd. Codes: billing_required, spending_limit, max_cost_exceeded, token_budget_exceeded.
{
"error": {
"code": "max_cost_exceeded",
"message": "This operation costs 0.002048576 USD, more than max_cost_usd allows (0.0001 USD). Raise max_cost_usd, or ask for less.",
"retryable": false,
"cost_usd": "0.002048576"
}
}403The credential can't do this: a publishable key, a key without Audit logs, a client token outside its grant, or a suspended team.
{
"error": {
"code": "forbidden",
"message": "Creating a ledger requires a secret API key (motor_sk_...) of the team, not a client token.",
"retryable": false
}
}404The resource doesn't exist for your team or your token's grant. A missing checkpoint is checkpoint_not_found.
{
"error": {
"code": "not_found",
"message": "The ledger doesn't exist.",
"retryable": false
}
}409A conflict. Codes: ledger_sealed, event_conflict, evidence_expiring, evidence_unavailable, snapshot_invalidated, capacity_exceeded, idempotency_conflict, request_in_progress.
{
"error": {
"code": "ledger_sealed",
"message": "The ledger is sealed, so it accepts no more events. Create another ledger for new events.",
"retryable": false,
"resource_id": "ald_LrB528wYtd4M8VJwtZikAt"
}
}413The body is too large: 512 KiB for an append, and 64 KiB otherwise.
{
"error": {
"code": "body_too_large",
"message": "The request body must be at most 524288 bytes.",
"retryable": false
}
}415The body isn't application/json.
{
"error": {
"code": "unsupported_media_type",
"message": "Send the request body as application/json.",
"retryable": false
}
}422A field, a query parameter, the cursor (invalid_cursor), or Motor-Mode (unsupported_mode) isn't valid.
{
"error": {
"code": "invalid_field",
"message": "`events[0].outcome` must be one of attempted, succeeded, failed, denied, unknown.",
"retryable": false
}
}429Too many requests: the team's requests or appended events, or 2 feed reads a second for each ledger. Retry after Retry-After.
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Retry after 1 seconds.",
"retryable": true,
"retry_after_seconds": 1
}
}503Motor can't sign checkpoints (signing_unavailable), a ledger is under an integrity check (integrity_check), or the billing month is closing. Retry later.
{
"error": {
"code": "signing_unavailable",
"message": "Motor can't sign checkpoints right now, so it doesn't accept new events. Motor didn't append or charge anything. Retry later.",
"retryable": true,
"retry_after_seconds": 60
}
}