OrbitsDocs
esc
    Open Orbits
    API reference · TeamUsage and activity

    Usage, activity and operations

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

    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.

    The usage object

    Fields

    • logs_availablebooleanrequired

      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.

    • monthstringrequired
    • currentbooleanrequired

      This month, so the series stops at today.

    • monthsarray of stringrequired

      From the team's first deployment to now, newest first.

    • daysarray of stringrequired

      The month's days so far.

    • totalsUsageTotalsrequired
      Show 6 child fields
      • requestsintegerrequired
      • bandwidth_bytesintegerrequired
      • build_minutesnumberrequired

        One decimal place.

      • function_runsintegerrequired
      • deploymentsintegerrequired
      • log_linesintegerrequired
    • deleted_projectsobjectrequired

      Usage of projects deleted since, which totals includes and by_project doesn't; zeros when there is none.

      Show 6 child fields
      • requestsintegerrequired
      • bandwidth_bytesintegerrequired
      • build_minutesnumberrequired

        One decimal place.

      • function_runsintegerrequired
      • deploymentsintegerrequired
      • log_linesintegerrequired
    • previousobject or nullrequired

      The same days of the month before; null when the team had no deployments before this month.

      Show 2 child fields
      • monthstringrequired
      • totalsUsageTotalsrequired
        Show 6 child fields
        • requestsintegerrequired
        • bandwidth_bytesintegerrequired
        • build_minutesnumberrequired

          One decimal place.

        • function_runsintegerrequired
        • deploymentsintegerrequired
        • log_linesintegerrequired
    • dailyarray of UsageDayrequired
      Show 2 child fields
      • datestringrequired
      • totalsUsageTotalsrequired
        Show 6 child fields
        • requestsintegerrequired
        • bandwidth_bytesintegerrequired
        • build_minutesnumberrequired

          One decimal place.

        • function_runsintegerrequired
        • deploymentsintegerrequired
        • log_linesintegerrequired
    • by_projectarray of objectrequired

      Every project the team has, most requests first. A deleted project's usage counts in the totals only.

      Show 8 child fields
      • project_idstringrequired
      • slugstringrequired
      • namestringrequired
      • totalsUsageTotalsrequired
        Show 6 child fields
        • requestsintegerrequired
        • bandwidth_bytesintegerrequired
        • build_minutesnumberrequired

          One decimal place.

        • function_runsintegerrequired
        • deploymentsintegerrequired
        • log_linesintegerrequired
      • previousUsageTotals or nullrequired
        Show 6 child fields
        • requestsintegerrequired
        • bandwidth_bytesintegerrequired
        • build_minutesnumberrequired

          One decimal place.

        • function_runsintegerrequired
        • deploymentsintegerrequired
        • log_linesintegerrequired
      • dailyarray of UsageDayrequired
        Show 2 child fields
        • datestringrequired
        • totalsUsageTotalsrequired
          Show 6 child fields
          • requestsintegerrequired
          • bandwidth_bytesintegerrequired
          • build_minutesnumberrequired

            One decimal place.

          • function_runsintegerrequired
          • deploymentsintegerrequired
          • log_linesintegerrequired
      • by_environmentobjectrequired

        Keyed by production, preview or development, for those with usage.

      • preview_branchesintegerrequired

        Branches with a preview deployment this month.

    The activity object

    Fields

    • idstringrequired
    • typestringrequired

      The event it was written from.

    • categorystringrequired

      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.

    • actorobjectrequired

      Who did it: a member (user), a commit's author for a push (git, no user_id), or Orbits itself (system).

      Show 3 child fields
      • kindstringrequired

        One of user, system, git.

      • user_idstring or nullrequired
      • namestringrequired
    • summarystringrequired

      The whole sentence, ready to show.

    • project_idstring or nullrequired
    • projectobject or nullrequired

      The project it's about, as it was named then.

      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired
    • deployment_idstring or nullrequired

      The deployment it's about, for a link to its page.

    • failedbooleanrequired

      A build that failed: the page shows the line in red.

    • created_atstringrequired

    The operation object

    Fields

    • idstringrequired
    • kindstringrequired
    • statestringrequired

      One of pending, running, succeeded, failed.

    • resourcestring
    • created_atstringrequired
    • finished_atstring or null
    • errornull or Problem
      Show 10 child fields
      • typestringrequired
      • titlestringrequired
      • statusintegerrequired
      • detailstring
      • instancestring
      • request_idstring
      • codestring

        A stable reason, where one is defined: plan_required (402); price_changed and already_pro (409) and billing_unavailable (503) from billing.

      • required_planstring

        On a 402: the plan that includes what was asked for.

        One of pro.

      • featurestring

        On a 402: what the plan lacks.

        One of functions, sandboxes, analytics, speed_insights.

      • errorsarray of object
        Show 2 child fields
        • fieldstringrequired
        • messagestringrequired

    A month of the team's usage, by day and by project

    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.

    GET/v1/teams/{team}/usage
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    Query parameters

    • monthstring

      Defaults to this month. A month still to come is 422.

    Response 200

    The month's usage.
    • logs_availablebooleanrequired

      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.

    • monthstringrequired
    • currentbooleanrequired

      This month, so the series stops at today.

    • monthsarray of stringrequired

      From the team's first deployment to now, newest first.

    • daysarray of stringrequired

      The month's days so far.

    • totalsUsageTotalsrequired
      Show 6 child fields
      • requestsintegerrequired
      • bandwidth_bytesintegerrequired
      • build_minutesnumberrequired

        One decimal place.

      • function_runsintegerrequired
      • deploymentsintegerrequired
      • log_linesintegerrequired
    • deleted_projectsobjectrequired

      Usage of projects deleted since, which totals includes and by_project doesn't; zeros when there is none.

      Show 6 child fields
      • requestsintegerrequired
      • bandwidth_bytesintegerrequired
      • build_minutesnumberrequired

        One decimal place.

      • function_runsintegerrequired
      • deploymentsintegerrequired
      • log_linesintegerrequired
    • previousobject or nullrequired

      The same days of the month before; null when the team had no deployments before this month.

      Show 2 child fields
      • monthstringrequired
      • totalsUsageTotalsrequired
        Show 6 child fields
        • requestsintegerrequired
        • bandwidth_bytesintegerrequired
        • build_minutesnumberrequired

          One decimal place.

        • function_runsintegerrequired
        • deploymentsintegerrequired
        • log_linesintegerrequired
    • dailyarray of UsageDayrequired
      Show 2 child fields
      • datestringrequired
      • totalsUsageTotalsrequired
        Show 6 child fields
        • requestsintegerrequired
        • bandwidth_bytesintegerrequired
        • build_minutesnumberrequired

          One decimal place.

        • function_runsintegerrequired
        • deploymentsintegerrequired
        • log_linesintegerrequired
    • by_projectarray of objectrequired

      Every project the team has, most requests first. A deleted project's usage counts in the totals only.

      Show 8 child fields
      • project_idstringrequired
      • slugstringrequired
      • namestringrequired
      • totalsUsageTotalsrequired
        Show 6 child fields
        • requestsintegerrequired
        • bandwidth_bytesintegerrequired
        • build_minutesnumberrequired

          One decimal place.

        • function_runsintegerrequired
        • deploymentsintegerrequired
        • log_linesintegerrequired
      • previousUsageTotals or nullrequired
        Show 6 child fields
        • requestsintegerrequired
        • bandwidth_bytesintegerrequired
        • build_minutesnumberrequired

          One decimal place.

        • function_runsintegerrequired
        • deploymentsintegerrequired
        • log_linesintegerrequired
      • dailyarray of UsageDayrequired
        Show 2 child fields
        • datestringrequired
        • totalsUsageTotalsrequired
          Show 6 child fields
          • requestsintegerrequired
          • bandwidth_bytesintegerrequired
          • build_minutesnumberrequired

            One decimal place.

          • function_runsintegerrequired
          • deploymentsintegerrequired
          • log_linesintegerrequired
      • by_environmentobjectrequired

        Keyed by production, preview or development, for those with usage.

      • preview_branchesintegerrequired

        Branches with a preview deployment this month.

    Errors

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

    Every code is explained in Errors.

    curl "https://api.theorbits.app/v1/teams/my-team/usage" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "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
        }
      ]
    }

    Team activity feed

    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.

    GET/v1/teams/{team}/activity
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    Query parameters

    • qstring

      Matches the sentence, the actor's name or the project's name, in any case.

      At most 200 characters.

    • actorstring

      A person's id from people.

    • projectstring

      A project's id or slug.

    • typestring

      One ActivityCategory, or several separated by commas.

    • sincestring

      Oldest line to return; defaults to 7 days ago, and is clamped to 90 days ago.

    • limitinteger

      From 1 to 100. Defaults to 25.

    • cursorstring

      next_cursor from the previous page.

    Response 200

    One page of lines, newest first, and how many match.
    • as_ofstringrequired
    • itemsarray of Activityrequired
      Show 10 child fields
      • idstringrequired
      • typestringrequired

        The event it was written from.

      • categorystringrequired

        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.

      • actorobjectrequired

        Who did it: a member (user), a commit's author for a push (git, no user_id), or Orbits itself (system).

        Show 3 child fields
        • kindstringrequired

          One of user, system, git.

        • user_idstring or nullrequired
        • namestringrequired
      • summarystringrequired

        The whole sentence, ready to show.

      • project_idstring or nullrequired
      • projectobject or nullrequired

        The project it's about, as it was named then.

        Show 3 child fields
        • idstringrequired
        • slugstringrequired
        • namestringrequired
      • deployment_idstring or nullrequired

        The deployment it's about, for a link to its page.

      • failedbooleanrequired

        A build that failed: the page shows the line in red.

      • created_atstringrequired
    • totalintegerrequired

      Lines that match the filters, counted up to 10,000.

      At most 10000.

    • total_cappedbooleanrequired

      More than 10,000 lines match, so total is 10,000.

    • next_cursorstring or nullrequired
    • anybooleanrequired

      Whether there is any activity at all, the other filters aside: in the team, or in the project when project is set. For the empty state.

    • peoplearray of objectrequired

      Everyone who appears in the feed (or the project's lines, with project), most recent first, for the person filter.

      Show 2 child fields
      • idstringrequired
      • namestringrequired
    • projectsarray of objectrequired

      Every project the feed mentions, most recent first, for the project filter.

      Show 3 child fields
      • idstringrequired
      • slugstringrequired
      • namestringrequired

    Errors

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

    Every code is explained in Errors.

    curl "https://api.theorbits.app/v1/teams/my-team/activity" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "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"
        }
      ]
    }

    Poll an asynchronous operation

    Poll an asynchronous operation.

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

    GET/v1/operations/{operation}
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • operationstringrequired

    Response 200

    The operation.
    • idstringrequired
    • kindstringrequired
    • statestringrequired

      One of pending, running, succeeded, failed.

    • resourcestring
    • created_atstringrequired
    • finished_atstring or null
    • errornull or Problem
      Show 10 child fields
      • typestringrequired
      • titlestringrequired
      • statusintegerrequired
      • detailstring
      • instancestring
      • request_idstring
      • codestring

        A stable reason, where one is defined: plan_required (402); price_changed and already_pro (409) and billing_unavailable (503) from billing.

      • required_planstring

        On a 402: the plan that includes what was asked for.

        One of pro.

      • featurestring

        On a 402: what the plan lacks.

        One of functions, sandboxes, analytics, speed_insights.

      • errorsarray of object
        Show 2 child fields
        • fieldstringrequired
        • messagestringrequired

    Errors

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

    Every code is explained in Errors.

    curl "https://api.theorbits.app/v1/operations/op_01jc8x6e4mq2v7r9y3t5b0zp8w" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "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"
          }
        ]
      }
    }

    Was this page helpful?

    Updated