# List events

Follow the returned `nextPageUrl` unchanged, preserving the original selection. An empty or
short page can still have a continuation. See [Pagination](https://augenta.pages.dev/docs/pagination.md).
After the final page, save `since` to poll for later recorded Events.

## GET `/v1/events`

Recorded Engram lifecycle events in committed order, including when source clocks go backward. Each event has its own stable id and a recorded identity-lineage payload in data.object. This feed does not contain every score or summary update. Follow nextPageUrl to finish the selected event range. Save since to poll for later events, using the same Workspace, engram filter and limit. One-shot results have no durable event feed.

## Authentication

Use an API key with the AugentaKey authorization scheme. See [Authentication](https://augenta.pages.dev/docs/authentication.md).

## Request example

```bash
curl --fail-with-body --get "https://api.augenta.ai/v1/events" \
  -H "Authorization: AugentaKey $AUGENTA_API_KEY" \
  --data-urlencode "workspace=$AUGENTA_WORKSPACE_ID"
```

## Parameters

<a id="request-parameters-workspace"></a>

### `request.parameters.workspace`

`string` · optional

query parameter. One assigned Workspace. Required for keys with multiple assignments; inferred for one.

<a id="request-parameters-limit"></a>

### `request.parameters.limit`

`integer` · optional

query parameter.

Default: `100`.

Minimum: `1`. Maximum: `500`.

<a id="request-parameters-page"></a>

### `request.parameters.page`

`string` · optional

query parameter. The previous memory cursor, with the same selection. Follow the returned nextPageUrl unchanged.

Min length: `1`. Max length: `131072`.

<a id="request-parameters-since"></a>

### `request.parameters.since`

`string` · optional

query parameter.

Min length: `1`. Max length: `4096`.

<a id="request-parameters-engram"></a>

### `request.parameters.engram`

`string` · optional

query parameter.

## Response 200

A page and an opaque polling bookmark.

Content-Type: `application/json`

<a id="response-200-object"></a>

### `response.200.object`

`string` · always present

Allowed values: `"list"`.

<a id="response-200-url"></a>

### `response.200.url`

`string` · always present

Allowed values: `"/v1/events"`.

<a id="response-200-data"></a>

### `response.200.data`

`array<value>` · always present

<a id="response-200-data-object"></a>

### `response.200.data.object`

`string` · always present

The resource type. Always event.

Allowed values: `"event"`.

<a id="response-200-data-id"></a>

### `response.200.data.id`

`string` · always present

The ID of this recorded Event, starting with evt\_. Use it with GET /v1/events/{id} in the same Workspace. Read data.object.id for the affected Engram's eng\_ ID. Snapshot Events are returned inline and have no stored lookup URL.

<a id="response-200-data-type"></a>

### `response.200.data.type`

`string` · always present

What happened: an Engram was created, changed membership, split, merged or retired. These Events do not report every score or summary update.

Allowed values: `"engram.created"`, `"engram.changed"`, `"engram.split"`, `"engram.merged"`, `"engram.retired"`.

<a id="response-200-data-created"></a>

### `response.200.data.created`

`integer` · always present

Recorded event time as Unix seconds. Workspace event feeds follow committed order even when source clocks go backward; one-shot events describe the completed rebuild.

<a id="response-200-data-data"></a>

### `response.200.data.data`

`object` · always present

The recorded identity-lineage payload. Completed memory results return the same Event resource in events. This is not a historical Engram snapshot or a complete score/prose audit.

<a id="response-200-data-data-object"></a>

### `response.200.data.data.object`

`object` · always present

<a id="response-200-data-data-object-object"></a>

### `response.200.data.data.object.object`

`string` · always present

The recorded payload type. Always engram_change.

Allowed values: `"engram_change"`.

<a id="response-200-data-data-object-kind"></a>

### `response.200.data.data.object.kind`

`string` · always present

What happened to the affected Engram's identity or Claim membership. The enclosing Event exposes the corresponding dotted type, such as engram.created for born.

Allowed values: `"born"`, `"update"`, `"split"`, `"merge"`, `"retire"`.

<a id="response-200-data-data-object-id"></a>

### `response.200.data.data.object.id`

`string` · always present

The ID of the Engram affected by this transition. This is an eng\_ ID, not the Event's evt\_ ID. The Engram may have been retired since this Event was recorded.

<a id="response-200-data-data-object-claimcountbefore"></a>

### `response.200.data.data.object.claimCountBefore`

`integer` · always present

The affected Engram's total current Claims immediately before this transition. Zero for a new Engram.

Minimum: `0`.

<a id="response-200-data-data-object-claimcountafter"></a>

### `response.200.data.data.object.claimCountAfter`

`integer` · always present

The affected Engram's total current Claims immediately after this transition. Zero when the identity is retired.

Minimum: `0`.

<a id="response-200-data-data-object-into"></a>

### `response.200.data.data.object.into`

`array<string>` · always present

New Engram IDs created by a split. Empty for other transition kinds.

See the [OpenAPI specification](https://augenta.pages.dev/docs/openapi.json) for deeper fields.

<a id="response-200-data-data-object-absorbed"></a>

### `response.200.data.data.object.absorbed`

`array<string>` · always present

Engram IDs merged into this surviving Engram and retired. Empty for other transition kinds.

See the [OpenAPI specification](https://augenta.pages.dev/docs/openapi.json) for deeper fields.

<a id="response-200-data-data-object-at"></a>

### `response.200.data.data.object.at`

`string` · always present

When this transition was recorded, as an ISO-8601 timestamp. The enclosing Event's created field represents the same time in Unix seconds.

<a id="response-200-nextpageurl"></a>

### `response.200.nextPageUrl`

`string | null` · always present

<a id="response-200-since"></a>

### `response.200.since`

`string` · always present

## Response 400

Invalid cursor, filter, limit or missing Workspace for a person or a key with multiple assignments.

Content-Type: `application/json`

<a id="response-400-error"></a>

### `response.400.error`

`object` · always present

<a id="response-400-error-code"></a>

### `response.400.error.code`

`string` · always present

Stable. The Errors page lists every code.

<a id="response-400-error-message"></a>

### `response.400.error.message`

`string` · always present

Human-readable. May change; don't parse it.

<a id="response-400-error-retryable"></a>

### `response.400.error.retryable`

`boolean` · always present

<a id="response-400-error-retryafterseconds"></a>

### `response.400.error.retryAfterSeconds`

`integer` · conditional

Capacity retry interval, also present as Retry-After before stream headers commit. SSE error events retain this field after HTTP 200 is committed.

Minimum: `1`.

<a id="response-400-error-billingurl"></a>

### `response.400.error.billingUrl`

`string` · conditional

Top-up action when error.code is insufficient_balance (HTTP 402).

<a id="response-400-requestid"></a>

### `response.400.requestId`

`string` · always present

The request's id, as in the `X-Request-Id` response header.

## Response 401

Authentication required; revoked credentials are refused.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 402

insufficient_balance: add credits before reading billable memory.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 403

Workspace access denied or Connector disabled.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 404

Workspace or engram not found.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 409

Workspace archived.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 429

rate_limited: retry after the Retry-After header.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 500

An internal failure; quote the requestId.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 502

Cognition failed or returned an invalid response.

Content-Type: `application/json`

Response fields use the same schema as Response 400.

## Response 503

Cognition is unavailable or unconfigured.

Content-Type: `application/json`

Response fields use the same schema as Response 400.
