# Billing

Your plan, this period's usage and your invoices. Read only.



{/* Generated from openapi/openapi.yaml by `npm run gen:api-docs`. Do not edit by hand. */}

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get this period's usage [#get-this-periods-usage]

    <ApiEndpointHeader method="GET" path="/v1/usage" scope="billing:read" />

    Running minutes, data transfer and storage, per AI team, for the current period.

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [Usage](#usage) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The usage.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/usage \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/usage', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/usage",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "usage",
      "period": {
        "start": "2026-10-01T00:00:00.000Z",
        "end": "2026-11-01T00:00:00.000Z"
      },
      "measured_at": "2026-10-15T06:00:00.000Z",
      "egress": {
        "used_gb": 12.4,
        "allowance_gb": 100,
        "over_allowance": false,
        "throttled": false
      },
      "storage": {
        "provisioned_gb": 50,
        "limit_gb": 200
      },
      "teams": [
        {
          "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
          "name": "Research",
          "running_minutes": 8640,
          "egress_gb": 12.4,
          "storage_gb": 20
        }
      ],
      "totals": {
        "running_minutes": 8640,
        "egress_gb": 12.4,
        "storage_gb": 20
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## Get your subscription [#get-your-subscription]

    <ApiEndpointHeader method="GET" path="/v1/billing/subscription" scope="billing:read" />

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a [Subscription](#subscription) object.

    <ApiParams title="Responses">
      <ApiParam name="200">
        The subscription.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/billing/subscription \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/billing/subscription', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/billing/subscription",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "subscription",
      "plan": "growth",
      "status": "active",
      "trial_ends_at": null,
      "current_period_end": "2026-11-28T00:00:00.000Z",
      "cancel_at_period_end": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ## List invoices [#list-invoices]

    <ApiEndpointHeader method="GET" path="/v1/billing/invoices" scope="billing:read" />

    Newest first. Pages forward with `starting_after` (an invoice id). Download links are not
    included: open invoices from Billing in HQ.

    <ApiParams title="Query parameters">
      <ApiParam name="limit" type="integer">
        How many objects to return, 1 to 100. Default 20.
      </ApiParam>

      <ApiParam name="starting_after" type="string">
        Return invoices older than this invoice id.
      </ApiParam>
    </ApiParams>

    <ApiParams title="Headers">
      <ApiParam name="HQ-Version" type="string (date)">
        A dated API version. Defaults to the version the key was created with.
      </ApiParam>

      <ApiParam name="HQ-Account" type="string">
        Agency keys only: the slug of the client organization this request acts for. Required with
        an agency key, refused with `400 invalid_request` on any other credential. A slug that is
        not one of your agency's current clients is `404 not_found`. An agency key is limited to
        600 requests a minute per key on EACH API server (the cap is per replica), plus its own
        budget per client (`limit_scope: agency_client`), separate from the client's own keys.
      </ApiParam>
    </ApiParams>

    **Returns** a list of [Invoice](#invoice) objects.

    <ApiParams title="Responses">
      <ApiParam name="200">
        A page of invoices.
      </ApiParam>

      <ApiParam name="Other">
        An RFC 9457 problem.
      </ApiParam>
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    <Tabs items="['cURL', 'JavaScript', 'Python']">
      <Tab value="cURL">
        ```bash
        curl https://api-hq.aiworkforceone.com/v1/billing/invoices \
          -H "Authorization: Bearer $HQ_API_KEY" \
          -H "HQ-Version: 2026-11-01"
        ```
      </Tab>

      <Tab value="JavaScript">
        ```js
        const res = await fetch('https://api-hq.aiworkforceone.com/v1/billing/invoices', {
          headers: {
            Authorization: `Bearer ${process.env['HQ_API_KEY']}`,
            'HQ-Version': '2026-11-01',
          },
        });
        console.log(await res.json());
        ```
      </Tab>

      <Tab value="Python">
        ```python
        import os

        import requests

        res = requests.get(
            "https://api-hq.aiworkforceone.com/v1/billing/invoices",
            headers={
                "Authorization": f"Bearer {os.environ['HQ_API_KEY']}",
                "HQ-Version": "2026-11-01",
            },
        )
        print(res.json())
        ```
      </Tab>
    </Tabs>

    ```json title="Response 200"
    {
      "object": "list",
      "data": [
        {
          "object": "invoice",
          "id": "in_1QzX8mK2eZvKYlo2C3tB9fRw",
          "number": "ACME-0012",
          "status": "paid",
          "amount_due": 49700,
          "amount_paid": 49700,
          "currency": "usd",
          "description": null,
          "period_start": "2026-09-28T00:00:00.000Z",
          "period_end": "2026-10-28T00:00:00.000Z",
          "created_at": "2026-09-28T00:04:12.000Z"
        }
      ],
      "has_more": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

## Objects [#objects]

<ApiEndpoint>
  <ApiEndpointMain>
    ### Usage [#usage]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="period" type="object" />

      <ApiParam name="measured_at" type="string or null" />

      <ApiParam name="egress" type="object" />

      <ApiParam name="storage" type="object" />

      <ApiParam name="teams" type="array of object" />

      <ApiParam name="totals" type="object" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The Usage object"
    {
      "object": "usage",
      "period": {
        "start": "2026-10-01T00:00:00.000Z",
        "end": "2026-11-01T00:00:00.000Z"
      },
      "measured_at": "2026-10-15T06:00:00.000Z",
      "egress": {
        "used_gb": 12.4,
        "allowance_gb": 100,
        "over_allowance": false,
        "throttled": false
      },
      "storage": {
        "provisioned_gb": 50,
        "limit_gb": 200
      },
      "teams": [
        {
          "team": "team_3kQ9vX2mR8tLpZ4wYc1aBd",
          "name": "Research",
          "running_minutes": 8640,
          "egress_gb": 12.4,
          "storage_gb": 20
        }
      ],
      "totals": {
        "running_minutes": 8640,
        "egress_gb": 12.4,
        "storage_gb": 20
      }
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### Subscription [#subscription]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="plan" type="string" />

      <ApiParam name="status" type="string" />

      <ApiParam name="trial_ends_at" type="string or null" />

      <ApiParam name="current_period_end" type="string or null" />

      <ApiParam name="cancel_at_period_end" type="boolean" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The Subscription object"
    {
      "object": "subscription",
      "plan": "growth",
      "status": "active",
      "trial_ends_at": null,
      "current_period_end": "2026-11-28T00:00:00.000Z",
      "cancel_at_period_end": false
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>

<ApiEndpoint>
  <ApiEndpointMain>
    ### Invoice [#invoice]

    <ApiParams title="Attributes">
      <ApiParam name="object" type="string" />

      <ApiParam name="id" type="string" />

      <ApiParam name="number" type="string or null" />

      <ApiParam name="status" type="string" />

      <ApiParam name="amount_due" type="integer">
        In the smallest currency unit.
      </ApiParam>

      <ApiParam name="amount_paid" type="integer" />

      <ApiParam name="currency" type="string" />

      <ApiParam name="description" type="string or null" />

      <ApiParam name="period_start" type="string (date-time)" />

      <ApiParam name="period_end" type="string (date-time)" />

      <ApiParam name="created_at" type="string (date-time)" />
    </ApiParams>
  </ApiEndpointMain>

  <ApiEndpointSamples>
    ```json title="The Invoice object"
    {
      "object": "invoice",
      "id": "in_1QzX8mK2eZvKYlo2C3tB9fRw",
      "number": "ACME-0012",
      "status": "paid",
      "amount_due": 49700,
      "amount_paid": 49700,
      "currency": "usd",
      "description": null,
      "period_start": "2026-09-28T00:00:00.000Z",
      "period_end": "2026-10-28T00:00:00.000Z",
      "created_at": "2026-09-28T00:04:12.000Z"
    }
    ```
  </ApiEndpointSamples>
</ApiEndpoint>
