# Events

An event is a notice that something happened in the organisation: a run finished, a review was decided, billing was paused. The same events are sent to your webhook endpoints; these calls list them, so you can catch up after downtime.

An event is a notice that something happened in the organisation: a run finished, a review was decided, billing was paused. The same events are sent to your webhook endpoints; these calls list them, so you can catch up after downtime.

## The Event object

An event is a notice that something happened in the organisation. It carries ids, links and counts, never the content of your files.

- `id` (string, required):
- `object` (string, required):  One of: `event`.
- `type` (string, required):
- `created` (string (date-time), required):
- `data` (object, required): What happened. `object` points at the thing it happened to: fetch it for its current state.
  - `object` (object, optional):
    - `id` (string, optional):
    - `type` (string, optional):
    - `url` (string, optional):

```json
{
  "id": "evt_8Zk2Qw0pVx3nLr5t",
  "object": "event",
  "type": "run.completed",
  "created": "string",
  "data": {
    "object": {
      "id": "string",
      "type": "string",
      "url": "string"
    }
  }
}
```

## List all events

`GET /api/v1/events`

Permission: Any.

Returns the organisation's recent events, newest first: the same notices a webhook endpoint is sent. Only events in areas your key can read are listed, and billing events only to owners. Page with `before` set to the previous page's `next`, an opaque value.

### Parameters

- `type` (string, optional): Only this type; repeat for several.
- `before` (string, optional): The previous page's `next`: an opaque cursor.
- `limit` (integer, optional): 1 to 100, default 50.

### Returns

A page of events.

### Errors

- 400: `limit` or `before` is refused.
- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`not_found`): `not_found`: “Not found.” An unknown id, or webhooks are off.
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/events \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Retrieve an event

`GET /api/v1/events/{id}`

Permission: Any.

Returns one event. An event in an area your key can't read answers 404, as an unknown id does.

### Parameters

- `id` (string, required):

### Returns

The event.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `403` for a role below the route's minimum (“Your role (\<role>) can't \<action>.”, or “Choose an organisation first.”), or, for an API key without the permission this call needs, code `wrong_key` with “This key needs the \<Area> · \<Read|Write> permission.” (for example “This key needs the Reviews · Write permission.”), or “This key can't do that.” for a call only the Mestra apps make.
- 404 (`not_found`): `not_found`: “Not found.” An unknown id, or webhooks are off.
- 409 (`api_off`): `409` with code `api_off` (“Turn on the API in Developer → API and MCP first.”): an owner hasn't turned the API on for this organisation, so no API key works yet. An owner turns it on in Settings, then API.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/events/string \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```
