# Export the audit log for a time range

`audit_event.export`

Returns the company's audit events created in [from, to) in the request's environment, plus any event the chain links between two of them whatever its createdAt, as a JSON Lines file (`application/jsonl`, `Content-Disposition` filename, `Content-Digest` SHA-256); send `Accept: application/json` for this JSON object. Each line is one event with every field its digest covers, so a reader verifies the chain without Arc: drop `digest` from the line, hash the rest as canonical JSON (keys sorted, no whitespace) with SHA-256, and compare. Each line's `prevDigest` is the line before's `digest`; the first line's is `firstPrevDigest`, the event before the range. A range holds at most 10,000 events created in it, with the linked events on top; a wider one refuses with invalid_request, so split it.

Callers: the account owner's CLI login, or an agent token with activity:read, or a personal access token with activity:read.

`GET /v1/audit-events/export`

Principal `user_session`. Idempotency `not_required`. Environment `either`.

## Input

| Field | In | Type | Description |
| --- | --- | --- | --- |
| `from` required | query | `string` | The first instant of the range, inclusive. |
| `to` required | query | `string` | The end of the range, exclusive. It must follow from. |
| `X-Hyperscale-Environment` | header | `sandbox \| live` |  |

## Output

| Field | Type | Description |
| --- | --- | --- |
| `contentType` required | `"application/jsonl"` |  |
| `filename` required | `string` |  |
| `content` required | `string` | One JSON object per line, in chain order: id, tenantId, environment, event, level, operationId, principalId, resourceKind, resourceId, body, createdAt, chainVersion, prevDigest and digest. An event the chain links between two in the range comes along even when its createdAt falls outside it, so every prevDigest names the line before. |
| `sha256` required | `string` | SHA-256 of content's UTF-8 bytes |
| `sizeBytes` required | `integer` |  |
| `eventCount` required | `integer` |  |
| `from` required | `string` |  |
| `to` required | `string` |  |
| `chainVersion` required | `"audit_event_digest_v1"` |  |
| `firstPrevDigest` required | `string \| null` | The digest the range's first event links to: the last event before from, or null when the range starts the chain or holds no events. |
| `lastDigest` required | `string \| null` | The range's last event's digest; null when it holds none. |

## Request sample

Only a signed-in person may call this: the CLI after hyperscale auth login, or curl with a personal access token (hyperscale_pat_...) with activity:read or an agent token with activity:read. The agent's grant must span every Product the call reads. A Product key cannot, so the SDK, which signs in with a Product key or a customer session, has no sample for it.

### curl

```shell
curl --request GET 'https://hyperscale0.ai/v1/audit-events/export' \
  --header "Authorization: Bearer $HYPERSCALE_TOKEN" \
  --header 'X-Hyperscale-Environment: sandbox'
```

### CLI

```shell
hyperscale api call audit_event.export
```

## Errors

| Code | HTTP | Cause |
| --- | --- | --- |
| `approval_rejected` | 403 | A person rejected the call or returned it to the maker, so it never runs. |
| `approval_required` | 202 | The call waits for decisions: an agent's call over its grant waits on its delegator, and a program action under `requires approval` waits on distinct people other than the maker. |
| `environment_mismatch` | 403 | The session was issued for sandbox or live and the request targets the other environment. |
| `internal_error` | 500 | Hyperscale hit an unexpected server-side condition and hid internal implementation details from this audience. |
| `invalid_request` | 400 | The request does not match the API reference. |
| `method_not_allowed` | 405 | The route exists, but not for the request's HTTP method. |
| `missing_required_permission` | 403 | The signed-in member's current role does not grant the permission required for this operation. |
| `missing_required_scope` | 403 | The credential is valid but does not grant one or more operation scopes. |
| `not_found` | 404 | No Hyperscale route matched the requested path and method. |
| `oauth_client_not_admitted` | 403 | The bearer is an OAuth client token, and this operation does not admit the oauth2_client principal. |
| `product_access_suspended` | 403 | The Product is disabled or closed, so its credentials are suspended in every environment. |
| `product_activation_required` | 403 | The live Product or required live capability is not active yet. |
| `rate_limited` | 429 | The credential sent more than its limit in the current 60-second window: 600 requests per API key or session, 1,200 per IP address. Every response carries `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset` (Unix seconds). |
| `resource_not_found` | 404 | The requested resource does not exist in the credential's visible scope. |
| `resource_reader_unavailable` | 503 | A generated read model could not serve the request at this moment. |
| `state_conflict` | 409 | The operation conflicts with the current durable state of the resource. |
| `tenant_mismatch` | 403 | The request mixed tenant-owned identifiers across tenant boundaries. |
| `tenant_not_found` | 404 | The credential resolved to a tenant Hyperscale cannot find. |
| `unauthorized` | 403 | The request did not include a valid Hyperscale bearer credential for this environment. |
| `agent_token_expired` | 401 | The agent token is real, but its grant ended. A grant lasts 30 days, or 7 days unused. `details.expiresAt` holds the date in ISO 8601 and `details.agentName` names the agent. |
| `agent_token_replaced` | 401 | The account owner ran `hyperscale agent setup` again for this agent, which replaced this token with a newer one. `details.agentName` names the agent and `details.replacedAt` holds the date. |
| `device_login_expired` | 401 | The bearer is the account owner's own device login from `hyperscale auth login`, not an agent token. Its access token lasts an hour and the CLI refreshes it; the login itself ends after 30 days, or 7 days unused. `details.expiresAt` holds when it ended in ISO 8601. |
| `invalid_credentials` | 401 | Hyperscale could not accept the account or credential request. Signup, login, and bearer authentication use one 401 for every case they reject, so the response exposes no credential-specific reason or registered-email verdict. The single exception is a key that is real but homed in the other environment: because the presented secret already matched a stored key, the message names the mismatch instead of leaving a working credential looking unknown. A bearer that matched nothing gets text that fits its prefix (an agent token, a refresh token, a personal access token, a session or no Hyperscale token at all), which says only what the caller sent, never whether a credential like it exists. |
| `session_expired` | 401 | The session behind this request has ended. A console session ends 30 days after sign-in, or after 12 hours with no request. An admin or customer session ends 24 hours after sign-in, or after 15 minutes with no request. A personal access token ends at the `expiresAt` set when it was created. |
| `session_required` | 401 | This operation needs a person signed in through the browser or the `hyperscale` CLI. A Product API key cannot call it. The request carried no session, or its token matched no live session. |
| `session_revoked` | 401 | The session or personal access token behind this request was ended before its expiry. Sign-out, `user.session.revoke`, a password reset, a role change, removal from the team, user suspension and `personal_access_token.revoke` all end sessions. |
| `tenant_status_forbidden` | 409 | The company is suspended or closed, so every credential bound to it is refused, reads included. `details.tenantId` names the company. |

[All operations](/docs/operations/index.md)

For agents: [OpenAPI document](https://hyperscale0.ai/openapi.json) · [MCP manifest](https://hyperscale0.ai/.well-known/mcp.json) · [HTTP API guide](https://hyperscale0.ai/docs/api.md) · [MCP guide](https://hyperscale0.ai/docs/mcp.md)