---
title: "List Events"
method: GET
path: "/v1/events"
tags: ["v1"]
---

# List Events

`GET /v1/events`

## Request

- Base URL: `https://api.korely.ai`
- URL: `https://api.korely.ai/v1/events`
- Auth: HTTP bearer

Which writes have finished being processed.

A write returns as soon as the memory is stored, then fact extraction runs
behind it. Without this endpoint a developer polls blind: they cannot tell
"extraction has not finished" from "there was nothing to extract", which is
the first confusing thing anyone hits when building on us.

`events` are the newest writes, newest first; `status` filters them before
`limit` is applied, so `?status=error` returns the most recent errors
however many ready writes came after them.

`processing` in the response is how many writes of this key's project (of
`user_id`, when given) are still in flight, counted over all of them, so a
batch import can wait on one number instead of walking every id. It ignores
`status` and `limit`.

No webhook announces that a write's extraction finished: `memory.created`
is sent when the memory is stored, before its facts, and
`GET /admin/webhooks/events` lists the events there are. Waiting for the
facts is polling this, or reading the memory again.

## Query parameters

- `user_id` string, nullable: Filter to one end user.
- `status` string, nullable: Filter to one processing state.
- `limit` integer

## Response `200`

Successful Response

- EventsResponse
  - `events` MemoryEvent[], required
    - `memory_id` string, required
    - `user_id` string, nullable, required
    - `agent_id` string, nullable, required
    - `status` string, required
    - `created_at` string, nullable, required
  - `processing` integer, required: Writes of this key's project (of `user_id`, when given) still in flight, counted over all of them. Independent of `status` and `limit`.

## Other responses

- `401`: `invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.
- `403`: `forbidden`: the key lacks the scope this operation needs; `message` names it.
- `422`: `invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).
- `429`: `rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).
- `500`: `internal_error`: the server failed on this request; `message` holds no detail of it.
- `503`: A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry.

---

[API](https://skmtc.dev/korely/apis/korely-agents-api.md) · [All operations](https://skmtc.dev/korely/apis/korely-agents-api/llms.txt) · [OpenAPI document](https://skmtc.dev/korely/apis/korely-agents-api/revisions/8a40bf09eca1?raw)