# Usage, activity and operations

What a team used, its activity feed, and the operations slow changes return.

Source: https://docs.orbits.africa/api/usage-and-activity

`GET .../usage` is what the team used in a period; `GET .../activity` is the feed of what happened, kept 90 days. A change that takes time answers `202` with an operation: poll `GET /v1/operations/{operation}` until its `state` is `succeeded` or `failed`.

Endpoints:

- `GET /v1/teams/{team}/usage`: A month of the team's usage, by day and by project
- `GET /v1/teams/{team}/activity`: Team activity feed
- `GET /v1/operations/{operation}`: Poll an asynchronous operation

## The usage object



- `logs_available` (boolean, required): False while the log store can't be reached: requests, bandwidth and function runs are then zeros, not a quiet month; builds and deployments still count. Show the log figures as unavailable.
- `month` (string, required)
- `current` (boolean, required): This month, so the series stops at today.
- `months` (array of string, required): From the team's first deployment to now, newest first.
- `days` (array of string, required): The month's days so far.
- `totals` (UsageTotals, required)
  - `requests` (integer, required)
  - `bandwidth_bytes` (integer, required)
  - `build_minutes` (number, required): One decimal place.
  - `function_runs` (integer, required)
  - `deployments` (integer, required)
  - `log_lines` (integer, required)
- `deleted_projects` (object, required): Usage of projects deleted since, which `totals` includes and `by_project` doesn't; zeros when there is none.
  - `requests` (integer, required)
  - `bandwidth_bytes` (integer, required)
  - `build_minutes` (number, required): One decimal place.
  - `function_runs` (integer, required)
  - `deployments` (integer, required)
  - `log_lines` (integer, required)
- `previous` (object or null, required): The same days of the month before; null when the team had no deployments before this month.
  - `month` (string, required)
  - `totals` (UsageTotals, required)
    - `requests` (integer, required)
    - `bandwidth_bytes` (integer, required)
    - `build_minutes` (number, required): One decimal place.
    - `function_runs` (integer, required)
    - `deployments` (integer, required)
    - `log_lines` (integer, required)
- `daily` (array of UsageDay, required)
  - `date` (string, required)
  - `totals` (UsageTotals, required)
    - `requests` (integer, required)
    - `bandwidth_bytes` (integer, required)
    - `build_minutes` (number, required): One decimal place.
    - `function_runs` (integer, required)
    - `deployments` (integer, required)
    - `log_lines` (integer, required)
- `by_project` (array of object, required): Every project the team has, most requests first. A deleted project's usage counts in the totals only.
  - `project_id` (string, required)
  - `slug` (string, required)
  - `name` (string, required)
  - `totals` (UsageTotals, required)
    - `requests` (integer, required)
    - `bandwidth_bytes` (integer, required)
    - `build_minutes` (number, required): One decimal place.
    - `function_runs` (integer, required)
    - `deployments` (integer, required)
    - `log_lines` (integer, required)
  - `previous` (UsageTotals or null, required)
    - `requests` (integer, required)
    - `bandwidth_bytes` (integer, required)
    - `build_minutes` (number, required): One decimal place.
    - `function_runs` (integer, required)
    - `deployments` (integer, required)
    - `log_lines` (integer, required)
  - `daily` (array of UsageDay, required)
    - `date` (string, required)
    - `totals` (UsageTotals, required)
      - `requests` (integer, required)
      - `bandwidth_bytes` (integer, required)
      - `build_minutes` (number, required): One decimal place.
      - `function_runs` (integer, required)
      - `deployments` (integer, required)
      - `log_lines` (integer, required)
  - `by_environment` (object, required): Keyed by `production`, `preview` or `development`, for those with usage.
  - `preview_branches` (integer, required): Branches with a preview deployment this month.
## The activity object



- `id` (string, required)
- `type` (string, required): The event it was written from.
- `category` (string, required): What a line is about, as the Activity page's type filter groups them. `domains` has no lines yet. One of `deployments`, `domains`, `members`, `variables`, `integrations`, `projects`, `team`.
- `actor` (object, required): Who did it: a member (`user`), a commit's author for a push (`git`, no `user_id`), or Orbits itself (`system`).
  - `kind` (string, required): One of `user`, `system`, `git`.
  - `user_id` (string or null, required)
  - `name` (string, required)
- `summary` (string, required): The whole sentence, ready to show.
- `project_id` (string or null, required)
- `project` (object or null, required): The project it's about, as it was named then.
  - `id` (string, required)
  - `slug` (string, required)
  - `name` (string, required)
- `deployment_id` (string or null, required): The deployment it's about, for a link to its page.
- `failed` (boolean, required): A build that failed: the page shows the line in red.
- `created_at` (string, required)
## The operation object



- `id` (string, required)
- `kind` (string, required)
- `state` (string, required): One of `pending`, `running`, `succeeded`, `failed`.
- `resource` (string)
- `created_at` (string, required)
- `finished_at` (string or null)
- `error` (null or Problem)
  - `type` (string, required)
  - `title` (string, required)
  - `status` (integer, required)
  - `detail` (string)
  - `instance` (string)
  - `request_id` (string)
  - `code` (string): A stable reason, where one is defined: `plan_required` (402); `price_changed` and `already_pro` (409) and `billing_unavailable` (503) from billing.
  - `required_plan` (string): On a 402: the plan that includes what was asked for. One of `pro`.
  - `feature` (string): On a 402: what the plan lacks. One of `functions`, `sandboxes`, `analytics`, `speed_insights`.
  - `errors` (array of object)
    - `field` (string, required)
    - `message` (string, required)
## A month of the team's usage, by day and by project

```http
GET /v1/teams/{team}/usage
```

The team's Usage page and its CSV, a project's Usage page (its `by_project` row), and the overview's usage panel. Days are Lagos days. `requests`, `bandwidth_bytes` (bytes the edge sent, headers included) and `log_lines` come from a daily rollup of the runtime logs kept 400 days; bandwidth is counted from when the edge started recording it, so earlier requests count 0 bytes. `build_minutes` (start to finish of each build, failed ones included) and `deployments` count deployments by the day they were created, back to the team's first. `function_runs` counts requests to projects with a `function` workload (also in `requests`): each is a call to the function, though functions run as one long-lived server until a per-call runtime ships. Figures for today are as of the call.

`previous` is the same days of the month before, for "+18% on September", or null when the team had no deployments before this month. `months` lists every month from the team's first deployment to now, newest first.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.

Query parameters:

- `month` (string): Defaults to this month. A month still to come is 422.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/usage" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "logs_available": false,
  "month": "2026-10",
  "current": false,
  "months": [
    "months"
  ],
  "days": [
    "2026-11-10"
  ],
  "totals": {
    "requests": 1,
    "bandwidth_bytes": 1,
    "build_minutes": 1,
    "function_runs": 1,
    "deployments": 1,
    "log_lines": 1
  },
  "deleted_projects": {
    "requests": 1,
    "bandwidth_bytes": 1,
    "build_minutes": 1,
    "function_runs": 1,
    "deployments": 1,
    "log_lines": 1
  },
  "previous": {
    "month": "month",
    "totals": {
      "requests": 1,
      "bandwidth_bytes": 1,
      "build_minutes": 1,
      "function_runs": 1,
      "deployments": 1,
      "log_lines": 1
    }
  },
  "daily": [
    {
      "date": "2026-11-10",
      "totals": {
        "requests": 1,
        "bandwidth_bytes": 1,
        "build_minutes": 1,
        "function_runs": 1,
        "deployments": 1,
        "log_lines": 1
      }
    }
  ],
  "by_project": [
    {
      "project_id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "slug": "my-app",
      "name": "my-app",
      "totals": {
        "requests": 1,
        "bandwidth_bytes": 1,
        "build_minutes": 1,
        "function_runs": 1,
        "deployments": 1,
        "log_lines": 1
      },
      "previous": {
        "requests": 1,
        "bandwidth_bytes": 1,
        "build_minutes": 1,
        "function_runs": 1,
        "deployments": 1,
        "log_lines": 1
      },
      "daily": [
        {
          "date": "2026-11-10",
          "totals": {
            "requests": 1,
            "bandwidth_bytes": 1,
            "build_minutes": 1,
            "function_runs": 1,
            "deployments": 1,
            "log_lines": 1
          }
        }
      ],
      "by_environment": {},
      "preview_branches": 1
    }
  ]
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Team activity feed

```http
GET /v1/teams/{team}/activity
```

The team's Activity page and its export: what happened across the team, newest first, one sentence each. Deployments (a preview started, production deployed, promoted or rolled back, a build failed), environment variables (added, updated, removed, restored, revealed, pulled), projects (created, renamed, settings changed, paused, deleted, moved in), members (joined, left, role changed), team settings and integrations (GitHub connected or disconnected). Invites and domains aren't in it yet. Lines are written from the platform's events a moment after they happen, kept 90 days, and read as they did then: a project or member renamed since keeps its old name in older lines.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.

Query parameters:

- `q` (string): Matches the sentence, the actor's name or the project's name, in any case. At most 200 characters.
- `actor` (string): A person's `id` from `people`.
- `project` (string): A project's `id` or `slug`.
- `type` (string): One `ActivityCategory`, or several separated by commas.
- `since` (string): Oldest line to return; defaults to 7 days ago, and is clamped to 90 days ago.
- `limit` (integer): From 1 to 100. Defaults to `25`.
- `cursor` (string): `next_cursor` from the previous page.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/activity" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "as_of": "2026-11-10T09:30:00Z",
  "items": [
    {
      "id": "act_0193a1f2-6c1e-7d2a-9b3f-1e2d3c4b5a69",
      "type": "project.production.changed",
      "category": "deployments",
      "actor": {
        "kind": "user",
        "user_id": "usr_01jc8x6e4mq2v7r9y3t5b0zp8w",
        "name": "my-app"
      },
      "summary": "Ada promoted a1f9c2e to production",
      "project_id": "prj_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "project": {
        "id": "act_01jc8x6e4mq2v7r9y3t5b0zp8w",
        "slug": "my-app",
        "name": "my-app"
      },
      "deployment_id": "dpl_01jc8x6e4mq2v7r9y3t5b0zp8w",
      "failed": false,
      "created_at": "2026-11-10T09:30:00Z"
    }
  ],
  "total": 1,
  "total_capped": false,
  "next_cursor": null,
  "any": false,
  "people": [
    {
      "id": "id",
      "name": "my-app"
    }
  ],
  "projects": [
    {
      "id": "id",
      "slug": "my-app",
      "name": "my-app"
    }
  ]
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## Poll an asynchronous operation

```http
GET /v1/operations/{operation}
```

Poll an asynchronous operation.

**Permissions:** The starter of the operation or an owner or admin of the team it ran in.

Token: any API token (`read` or `full`).

Path parameters:

- `operation`

Example:

```sh
curl "https://api.theorbits.app/v1/operations/op_01jc8x6e4mq2v7r9y3t5b0zp8w" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "id": "op_01jc8x6e4mq2v7r9y3t5b0zp8w",
  "kind": "team.delete",
  "state": "pending",
  "resource": "resource",
  "created_at": "2026-11-10T09:30:00Z",
  "finished_at": "2026-11-10T09:30:00Z",
  "error": {
    "type": "https://my-app.theorbits.app",
    "title": "title",
    "status": 1,
    "detail": "detail",
    "instance": "instance",
    "request_id": "request-id",
    "code": "code",
    "required_plan": "pro",
    "feature": "functions",
    "errors": [
      {
        "field": "field",
        "message": "message"
      }
    ]
  }
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
