# Projects, keys and tokens

> Create projects, ingest keys and API tokens on a self-hosted engine, manage keys and tokens anywhere, and read usage.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/api/projects-keys-and-tokens/

For agents: Reference of the Projects, keys and tokens endpoints of the Sypnia HTTP API: parameters, response shapes, examples and errors.

The engine knows three things about access: projects, ingest keys and API tokens. It has no users and no
organizations. Those exist only in Sypnia Cloud, in the app, and have no public API at launch.

| You want to                                 | Engine (self-hosted)                                             | Sypnia Cloud                                  |
| ------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------- |
| Create or delete a project                  | This API, with the root token                                    | In the app                                    |
| Create or revoke ingest keys and API tokens | This API, with the root token or an `admin` token of the project | This API with an `admin` token, or in the app |
| Invite people, change plan, see invoices    | Does not exist                                                   | In the app                                    |

## The project object

**Fields:**

- `id` (string, optional): `prj_…`.
- `slug` (string, optional): A short name for URLs and commands. Lowercase letters, digits and hyphens, 2 to 40 characters. Cannot be changed.
- `name` (string, optional): The name people see.
- `timezone` (string, optional): An IANA time zone. Days, «today» and «yesterday» are cut in it.
- `environments` (array of string, optional): The environments that sent data in the last 30 days.
- `settings` (object, optional)
- `settings.allowed_origins` (array of string, up to 50 items): Origins allowed to send browser data, such as `https://shop.example.com`. A leading `*.` matches subdomains. Empty accepts any origin.
- `settings.replay` (object): Recording rules. The SDK reads them from the ingest's config call.
- `settings.replay.enabled` (boolean, default `true`): `false` switches replay off for the project.
- `settings.replay.sample_rate` (number, 0 to 1, default `0.1`): The share of sessions recorded from their first moment. Sessions outside it are still recorded from 30 seconds before their first error, rage click or dead click.
- `settings.replay.mask_all_text` (boolean, default `false`): `true` masks every text on the page, not only what people type. What people type is always masked, and password, card and one-time-code fields can never be unmasked.
- `settings.replay.blocked_routes` (array of string, up to 100 items): Routes where nothing is recorded and no snapshot is taken. `*` matches any characters: `/account/*`.
- `settings.replay.always_record` (array of object, up to 100 items): People and accounts whose sessions are always recorded from the start, for example while you help a customer.
- `settings.snapshots` (object)
- `settings.snapshots.sample_rate` (number, 0 to 1, default `0.5`): The share of sessions that take page snapshots, for click maps.
- `settings.agent` (object)
- `settings.agent.enabled` (boolean, default `true`): `false` switches the agent off for this project: no analysis, no weekly suggestions from a model. Nothing is sent to an AI provider.
- `settings.agent.language` (string, default `en`): The language the agent writes in, as a BCP 47 tag (`en`, `es`).
- `settings.agent.auto_pull_requests` (string, default `off`): Sypnia Cloud only. `high_confidence` opens a pull request by itself when an analysis is `high`. One of: `off`, `high_confidence`.
- `created_at` (timestamp, optional)

## The ingest key object

**Fields:**

- `id` (string, optional): The record's id, `key_…`. Use it to revoke the key.
- `key` (string, optional): The key itself, `spk_` and 32 hex characters. Public: it goes in your app's code.
- `name` (string, optional)
- `rate_limit_per_minute` (integer, optional): Requests per minute accepted from one address with this key.
- `created_at` (timestamp, optional)
- `last_used_at` (timestamp or null, optional): Accurate to the hour.
- `revoked_at` (timestamp or null, optional)

## The API token object

**Fields:**

- `id` (string, optional): The record's id, `tok_…`. Use it to revoke the token.
- `name` (string, optional)
- `prefix` (string, optional): The first 12 characters of the secret.
- `scopes` (array of string, optional): One of: `read`, `replay`, `admin`.
- `created_at` (timestamp, optional)
- `last_used_at` (timestamp or null, optional): Accurate to the hour.
- `expires_at` (timestamp or null, optional)
- `revoked_at` (timestamp or null, optional)

## List projects

`GET /v1/projects` \[Engine, Cloud]

With the root token, every project of the engine. With an API token, a list with the one project the token belongs to.

**Authentication:** Root token, or API token (`read`)

**Query parameters:**

- `limit` (integer, 1 to 200, optional, default `50`): Most items to return.
- `cursor` (string, optional): The `next_cursor` of the previous page. Keep every other parameter the same.

**Request:**

```bash
curl "https://sypnia.example.com/v1/projects" \
  -H "Authorization: Bearer $SYPNIA_ROOT_TOKEN"
```

**Response (200):**

```json
{
  "data": [
    {
      "id": "prj_5k2m9x4q7w1z",
      "slug": "shop",
      "name": "Shop",
      "timezone": "UTC",
      "environments": [
        "production",
        "development"
      ],
      "settings": {
        "allowed_origins": [
          "https://shop.example.com"
        ],
        "replay": {
          "enabled": true,
          "sample_rate": 0.1,
          "mask_all_text": false,
          "blocked_routes": [
            "/account/cards"
          ],
          "always_record": [
            {
              "person": "u_1042",
              "note": "Reported the checkout bug",
              "until": "2026-03-26T00:00:00Z"
            }
          ]
        },
        "snapshots": {
          "sample_rate": 0.5
        },
        "agent": {
          "enabled": true,
          "language": "en",
          "auto_pull_requests": "off"
        }
      },
      "created_at": "2026-02-02T09:15:00Z"
    }
  ],
  "next_cursor": null
}
```

## Create a project

`POST /v1/projects` \[Engine]

Creates a project and its first ingest key, which comes back in `ingest_key`. Self-hosted engines only: on
Sypnia Cloud projects are created in the app, where they belong to an organization and a plan, and this call
answers `403 cloud_managed`.

**Authentication:** Root token

**Headers:**

- `Idempotency-Key` (string, up to 255 characters, optional): A value of your own, 1 to 255 characters, that makes the call safe to repeat. See [idempotency](https://docs.sypnia.com/api/errors-limits-pagination#idempotency).

**Body:**

- `name` (string, up to 80 characters, required): The name people see.
- `slug` (string, optional): Defaults to the name in lowercase with hyphens.
- `timezone` (string, optional, default `UTC`): An IANA time zone, such as `America/Bogota`.
- `settings` (object, optional)
- `settings.allowed_origins` (array of string, up to 50 items): Origins allowed to send browser data, such as `https://shop.example.com`. A leading `*.` matches subdomains. Empty accepts any origin.
- `settings.replay` (object): Recording rules. The SDK reads them from the ingest's config call.
- `settings.replay.enabled` (boolean, default `true`): `false` switches replay off for the project.
- `settings.replay.sample_rate` (number, 0 to 1, default `0.1`): The share of sessions recorded from their first moment. Sessions outside it are still recorded from 30 seconds before their first error, rage click or dead click.
- `settings.replay.mask_all_text` (boolean, default `false`): `true` masks every text on the page, not only what people type. What people type is always masked, and password, card and one-time-code fields can never be unmasked.
- `settings.replay.blocked_routes` (array of string, up to 100 items): Routes where nothing is recorded and no snapshot is taken. `*` matches any characters: `/account/*`.
- `settings.replay.always_record` (array of object, up to 100 items): People and accounts whose sessions are always recorded from the start, for example while you help a customer.
- `settings.snapshots` (object)
- `settings.snapshots.sample_rate` (number, 0 to 1, default `0.5`): The share of sessions that take page snapshots, for click maps.
- `settings.agent` (object)
- `settings.agent.enabled` (boolean, default `true`): `false` switches the agent off for this project: no analysis, no weekly suggestions from a model. Nothing is sent to an AI provider.
- `settings.agent.language` (string, default `en`): The language the agent writes in, as a BCP 47 tag (`en`, `es`).
- `settings.agent.auto_pull_requests` (string, default `off`): Sypnia Cloud only. `high_confidence` opens a pull request by itself when an analysis is `high`. One of: `off`, `high_confidence`.

**Request:**

```bash
curl -X POST "https://sypnia.example.com/v1/projects" \
  -H "Authorization: Bearer $SYPNIA_ROOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Shop", "slug": "shop", "timezone": "UTC"}'
```

**Response (201):**

```json
{
  "id": "prj_5k2m9x4q7w1z",
  "slug": "shop",
  "name": "Shop",
  "timezone": "UTC",
  "environments": [],
  "settings": {
    "allowed_origins": [],
    "replay": {
      "enabled": true,
      "sample_rate": 0.1,
      "mask_all_text": false,
      "blocked_routes": [],
      "always_record": []
    },
    "snapshots": {
      "sample_rate": 0.5
    },
    "agent": {
      "enabled": true,
      "language": "en",
      "auto_pull_requests": "off"
    }
  },
  "created_at": "2026-02-02T09:15:00Z",
  "ingest_key": {
    "id": "key_3n8v2c6b1m4x",
    "key": "spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e",
    "name": "Default",
    "rate_limit_per_minute": 600,
    "created_at": "2026-02-02T09:15:00Z",
    "last_used_at": null,
    "revoked_at": null
  }
}
```

**Errors:**

- `400` `invalid_request`: `name` is missing, `slug` has characters other than `a-z 0-9 -`, or `timezone` is not an IANA name.
- `403` `cloud_managed`: The request went to Sypnia Cloud. Create projects in the app.
- `403` `forbidden`: The credential is not the root token.
- `409` `conflict`: A project with this `slug` exists.

## Get a project

`GET /v1/projects/{project_ref}` \[Engine, Cloud]

One project with its settings.

**Authentication:** Root token, or API token (`read`) of that project

**Path parameters:**

- `project_ref` (string, required): The project's id (`prj_…`) or slug.

**Request:**

```bash
curl "https://api.sypnia.com/v1/projects/shop" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "id": "prj_5k2m9x4q7w1z",
  "slug": "shop",
  "name": "Shop",
  "timezone": "UTC",
  "environments": [
    "production",
    "development"
  ],
  "settings": {
    "allowed_origins": [
      "https://shop.example.com"
    ],
    "replay": {
      "enabled": true,
      "sample_rate": 0.1,
      "mask_all_text": false,
      "blocked_routes": [
        "/account/cards"
      ],
      "always_record": [
        {
          "person": "u_1042",
          "note": "Reported the checkout bug",
          "until": "2026-03-26T00:00:00Z"
        }
      ]
    },
    "snapshots": {
      "sample_rate": 0.5
    },
    "agent": {
      "enabled": true,
      "language": "en",
      "auto_pull_requests": "off"
    }
  },
  "created_at": "2026-02-02T09:15:00Z"
}
```

**Errors:**

- `404` `not_found`: No such project, or the token belongs to another one.

## Update a project

`PATCH /v1/projects/{project_ref}` \[Engine, Cloud]

Changes the fields you send and leaves the rest. `settings` is merged key by key: send only the settings you
want to change. Recording rules (`settings.replay`, `settings.snapshots`) reach browsers with their next
session, through the ingest's config call; no deploy is needed.

**Authentication:** Root token, or API token (`admin`) of that project

**Path parameters:**

- `project_ref` (string, required): The project's id (`prj_…`) or slug.

**Body:**

- `name` (string, up to 80 characters, optional): The name people see.
- `timezone` (string, optional): An IANA time zone. Past days are not recut.
- `settings` (object, optional)
- `settings.allowed_origins` (array of string, up to 50 items): Origins allowed to send browser data, such as `https://shop.example.com`. A leading `*.` matches subdomains. Empty accepts any origin.
- `settings.replay` (object): Recording rules. The SDK reads them from the ingest's config call.
- `settings.replay.enabled` (boolean, default `true`): `false` switches replay off for the project.
- `settings.replay.sample_rate` (number, 0 to 1, default `0.1`): The share of sessions recorded from their first moment. Sessions outside it are still recorded from 30 seconds before their first error, rage click or dead click.
- `settings.replay.mask_all_text` (boolean, default `false`): `true` masks every text on the page, not only what people type. What people type is always masked, and password, card and one-time-code fields can never be unmasked.
- `settings.replay.blocked_routes` (array of string, up to 100 items): Routes where nothing is recorded and no snapshot is taken. `*` matches any characters: `/account/*`.
- `settings.replay.always_record` (array of object, up to 100 items): People and accounts whose sessions are always recorded from the start, for example while you help a customer.
- `settings.snapshots` (object)
- `settings.snapshots.sample_rate` (number, 0 to 1, default `0.5`): The share of sessions that take page snapshots, for click maps.
- `settings.agent` (object)
- `settings.agent.enabled` (boolean, default `true`): `false` switches the agent off for this project: no analysis, no weekly suggestions from a model. Nothing is sent to an AI provider.
- `settings.agent.language` (string, default `en`): The language the agent writes in, as a BCP 47 tag (`en`, `es`).
- `settings.agent.auto_pull_requests` (string, default `off`): Sypnia Cloud only. `high_confidence` opens a pull request by itself when an analysis is `high`. One of: `off`, `high_confidence`.

**Request:**

```bash
curl -X PATCH "https://api.sypnia.com/v1/projects/shop" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"replay": {"blocked_routes": ["/account/cards"]}}}'
```

**Response (200):**

```json
{
  "id": "prj_5k2m9x4q7w1z",
  "slug": "shop",
  "name": "Shop",
  "timezone": "UTC",
  "environments": [
    "production",
    "development"
  ],
  "settings": {
    "allowed_origins": [
      "https://shop.example.com"
    ],
    "replay": {
      "enabled": true,
      "sample_rate": 0.1,
      "mask_all_text": false,
      "blocked_routes": [
        "/account/cards"
      ],
      "always_record": [
        {
          "person": "u_1042",
          "note": "Reported the checkout bug",
          "until": "2026-03-26T00:00:00Z"
        }
      ]
    },
    "snapshots": {
      "sample_rate": 0.5
    },
    "agent": {
      "enabled": true,
      "language": "en",
      "auto_pull_requests": "off"
    }
  },
  "created_at": "2026-02-02T09:15:00Z"
}
```

**Errors:**

- `400` `invalid_request`: A setting is out of range or unknown. `param` names it, for example `settings.replay.sample_rate`.
- `404` `not_found`: No such project, or the token belongs to another one.

## Delete a project

`DELETE /v1/projects/{project_ref}` \[Engine]

Deletes the project, its keys and tokens, and all of its data, for good. Ingest for its keys stops at once;
stored objects are removed within 24 hours. Self-hosted engines only. To confirm, send the project's slug in
the `confirm` query parameter.

**Authentication:** Root token

**Path parameters:**

- `project_ref` (string, required): The project's id (`prj_…`) or slug.

**Query parameters:**

- `confirm` (string, required): The project's slug, typed again.

**Request:**

```bash
curl -X DELETE "https://sypnia.example.com/v1/projects/shop?confirm=shop" \
  -H "Authorization: Bearer $SYPNIA_ROOT_TOKEN"
```

**Errors:**

- `400` `invalid_request`: `confirm` is missing or is not the project's slug.
- `403` `cloud_managed`: The request went to Sypnia Cloud. Delete projects in the app.
- `404` `not_found`: No such project.

## List ingest keys

`GET /v1/keys` \[Engine, Cloud]

The project's ingest keys, including revoked ones. An ingest key is public, so the list shows each key in full.

**Authentication:** Root token, or API token (`admin`)

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Request:**

```bash
curl "https://api.sypnia.com/v1/keys" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Response (200):**

```json
{
  "data": [
    {
      "id": "key_3n8v2c6b1m4x",
      "key": "spk_7d1f0c9e4b8a2f6d3c5e1a9b0f4d8c2e",
      "name": "Web app",
      "rate_limit_per_minute": 600,
      "created_at": "2026-02-02T09:15:00Z",
      "last_used_at": "2026-03-12T10:31:58Z",
      "revoked_at": null
    }
  ],
  "next_cursor": null
}
```

## Create an ingest key

`POST /v1/keys` \[Engine, Cloud]

Creates another ingest key for the project. Give each app or platform its own key (web, mobile, server), so you can revoke one without stopping the others. A project has at most 20 keys that are not revoked.

**Authentication:** Root token, or API token (`admin`)

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Headers:**

- `Idempotency-Key` (string, up to 255 characters, optional): A value of your own, 1 to 255 characters, that makes the call safe to repeat. See [idempotency](https://docs.sypnia.com/api/errors-limits-pagination#idempotency).

**Body:**

- `name` (string, up to 80 characters, required): What the key is for.
- `rate_limit_per_minute` (integer, 10 to 6,000, optional, default `600`): Requests per minute accepted from one address with this key. Raise it for a server that sends for many people from one address.

**Request:**

```bash
curl -X POST "https://api.sypnia.com/v1/keys" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Checkout API"}'
```

**Response (201):**

```json
{
  "id": "key_8b5n2m7v4c1x",
  "key": "spk_a3c9e1f7b5d2084c6e0a9f3b7d1c5e82",
  "name": "Checkout API",
  "rate_limit_per_minute": 600,
  "created_at": "2026-03-12T10:40:00Z",
  "last_used_at": null,
  "revoked_at": null
}
```

**Errors:**

- `409` `limit_reached`: The project already has 20 keys that are not revoked.

## Revoke an ingest key

`DELETE /v1/keys/{key_id}` \[Engine, Cloud]

Revokes the key. Ingest with it answers `401` within one minute. The record stays in the list with `revoked_at`. Revoking cannot be undone; create a new key instead.

**Authentication:** Root token, or API token (`admin`)

**Path parameters:**

- `key_id` (string, required): The key's record id (`key_…`), not the key itself.

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Request:**

```bash
curl -X DELETE "https://api.sypnia.com/v1/keys/key_8b5n2m7v4c1x" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Errors:**

- `404` `not_found`: No key has this id in the project.
- `409` `conflict`: It is the project's last key that is not revoked. Create another first, so your app is never without one.

## List API tokens

`GET /v1/tokens` \[Engine, Cloud]

The project's API tokens, including revoked and expired ones. The secret is never shown again; `prefix` is its first 12 characters, enough to recognise it.

**Authentication:** Root token, or API token (`admin`)

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Request:**

```bash
curl "https://api.sypnia.com/v1/tokens" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Response (200):**

```json
{
  "data": [
    {
      "id": "tok_9r4t6y2u8i1o",
      "name": "Cursor",
      "prefix": "sps_4Kq9Zt2M",
      "scopes": [
        "read",
        "replay"
      ],
      "created_at": "2026-02-02T09:18:00Z",
      "last_used_at": "2026-03-12T10:34:10Z",
      "expires_at": null,
      "revoked_at": null
    }
  ],
  "next_cursor": null
}
```

## Create an API token

`POST /v1/tokens` \[Engine, Cloud]

Creates an API token for the project. The secret is in `token` and is shown **only in this answer**: the
engine stores a hash of it. Give a token the fewest scopes that do the job:

| Scope    | What it allows                                                                                                                                                 |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read`   | Read everything except replay content. Its only writes are reversible marks: resolve or reopen a problem, acknowledge an alert, set a suggestion's status      |
| `replay` | Fetch replays and page snapshots. They show the page as the person saw it                                                                                      |
| `admin`  | Everything that changes the project: keys, tokens, settings, releases and source maps, uptime checks, alert rules, webhooks, ignoring a problem, deleting data |

Scopes do not include each other: a token that should read and manage needs `read` and `admin`.

**Authentication:** Root token, or API token (`admin`)

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Headers:**

- `Idempotency-Key` (string, up to 255 characters, optional): A value of your own, 1 to 255 characters, that makes the call safe to repeat. See [idempotency](https://docs.sypnia.com/api/errors-limits-pagination#idempotency).

**Body:**

- `name` (string, up to 80 characters, required): Who or what will use it. It appears in `resolved_by` and in the audit of changes.
- `scopes` (array of string, required): What the token may do. One of: `read`, `replay`, `admin`.
- `expires_at` (timestamp, optional): When the token stops working. Leave it out for a token that does not expire.

**Request:**

```bash
curl -X POST "https://api.sypnia.com/v1/tokens" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Cursor", "scopes": ["read", "replay"]}'
```

**Response (201):**

```json
{
  "id": "tok_9r4t6y2u8i1o",
  "name": "Cursor",
  "prefix": "sps_4Kq9Zt2M",
  "token": "sps_4Kq9Zt2MxV7bN1cR5wY8pL3dF6hJ0sA2gE4uT9iO",
  "scopes": [
    "read",
    "replay"
  ],
  "created_at": "2026-02-02T09:18:00Z",
  "last_used_at": null,
  "expires_at": null,
  "revoked_at": null
}
```

**Errors:**

- `400` `invalid_request`: `scopes` is empty or has a value other than `read`, `replay`, `admin`; or `expires_at` is in the past.
- `409` `limit_reached`: The project already has 50 tokens that are not revoked.

## Revoke an API token

`DELETE /v1/tokens/{token_id}` \[Engine, Cloud]

Revokes the token. Requests with it answer `401` within one minute. A token may revoke itself.

**Authentication:** Root token, or API token (`admin`)

**Path parameters:**

- `token_id` (string, required): The token's record id (`tok_…`), not the secret.

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.

**Request:**

```bash
curl -X DELETE "https://api.sypnia.com/v1/tokens/tok_9r4t6y2u8i1o" \
  -H "Authorization: Bearer $SYPNIA_ADMIN_TOKEN"
```

**Errors:**

- `404` `not_found`: No token has this id in the project.

## Get usage and limits

`GET /v1/usage` \[Engine, Cloud]

What the project used in the current period and what its limits are. A limit of `null` means no limit: that is
every limit on a self-hosted engine unless you set a quota in its configuration. On Sypnia Cloud the limits
are the plan's and the period is the calendar month, in UTC. A plan's limits belong to the organization and
are shared by its projects: `used` is this project's part, `organization_used` is what all its projects used
together, and the limit is reached when `organization_used` reaches `limit`.

Counters are exact and updated as data arrives. `dropped_over_limit` is how many events or replays were
refused because a limit was reached: Sypnia never drops silently, it counts here and tells the SDK to slow
down.

| Counter         | What counts as one                                                                                                                                         |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `events`        | An error, a trace (one request with its spans) or a performance sample (a page view with its vitals). Clicks, custom events and replay chunks do not count |
| `replays`       | A session that has a recording                                                                                                                             |
| `analyses`      | One run of the agent on one problem. Counted per day                                                                                                       |
| `pull_requests` | A pull request opened by Sypnia. Sypnia Cloud only                                                                                                         |

**Authentication:** API token (`read`)

**Query parameters:**

- `project` (string, optional): The project's id or slug. Needed only with a credential that can see several projects (the root token). With an API token it is ignored unless it names another project, which is `403`.
- `period` (string, optional): A month as `YYYY-MM`, to read a past period. Up to 12 months back.

**Request:**

```bash
curl "https://api.sypnia.com/v1/usage" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN"
```

**Response (200):**

```json
{
  "project": {
    "id": "prj_5k2m9x4q7w1z",
    "slug": "shop",
    "name": "Shop"
  },
  "plan": "builder",
  "period": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-04-01T00:00:00Z"
  },
  "events": {
    "used": 18240,
    "organization_used": 21902,
    "limit": 50000,
    "dropped_over_limit": 0
  },
  "replays": {
    "used": 212,
    "organization_used": 240,
    "limit": 500,
    "dropped_over_limit": 0
  },
  "analyses": {
    "used_today": 4,
    "limit_per_day": 100,
    "used_this_period": 37
  },
  "pull_requests": {
    "used": 6,
    "organization_used": 6,
    "limit": 50,
    "dropped_over_limit": 0
  },
  "uptime_checks": {
    "used": 1,
    "limit": 5
  },
  "retention_days": {
    "events": 30,
    "replays": 30
  },
  "slow_down": null,
  "daily": [
    {
      "day": "2026-03-11",
      "events": 1610,
      "replays": 19,
      "analyses": 2
    },
    {
      "day": "2026-03-12",
      "events": 702,
      "replays": 9,
      "analyses": 4
    }
  ]
}
```

The errors every endpoint can answer (`401`, `403`, `429`, `500`, `503`) are on [Errors, limits, pagination](https://docs.sypnia.com/api/errors-limits-pagination).
