> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing aggregation

> Sum spend over a period and break it down by day, app, or credential.

**`GET`** `https://api-datahub.octoparse.com/v1/billing`

Authentication: API key required (`Authorization: Bearer <API Key>`).

How much you spent in a period, and where. Independent of the account identity endpoint.

The time range uses the same vocabulary as <a href="/docs/en/datahub/api/reference/runs/list-runs">List runs</a>: `created_from` / `created_to` are inclusive/exclusive ISO-8601 absolute times keyed by run **start** time. Pass the same bounds into List runs to drill into the runs behind any group total. `tz_offset` only decides which local day a run lands in for day buckets; it does not change amounts or the absolute range itself.

Only data fees are aggregated. Day groups ascend for reconciliation; app and credential groups descend by amount so the largest spend shows first.

The `credential` breakdown answers “how much did each of my keys spend?”. The key is a non-sensitive stable credential id, the same value used by the List runs `credential` filter. Scope is always your account; you never see someone else’s credentials.

## Request

### Query parameters

<ParamField query="group_by" type="string" default="day">
  Breakdown dimension: `day` (default), `data_app`, or `credential`.
</ParamField>

<ParamField query="created_from" type="string">
  Inclusive start. Omit to start from the earliest run.
</ParamField>

<ParamField query="created_to" type="string">
  Exclusive end. Omit to include up to now.
</ParamField>

<ParamField query="tz_offset" type="integer" default="0">
  Day-bucket timezone offset in minutes from UTC. Use `480` for China Standard Time; default `0` is UTC days. Fixed offset only (no DST). Drill-down `created_from` / `created_to` must use the same offset. Range -720 to 840.
</ParamField>

### Example request

```bash theme={null}
curl \
  -H "Authorization: Bearer $OCTOPARSE_API_KEY" \
  "https://api-datahub.octoparse.com/v1/billing?group_by=day&created_from=2026-09-01T00:00:00%2B00:00&created_to=2026-10-01T00:00:00%2B00:00&tz_offset=0"
```

## Response

### 200 success

```json theme={null}
{
  "data": {
    "total": 0.08,
    "currency": "USD",
    "group_by": "day",
    "groups": [
      {
        "day": "2026-07-01",
        "namespace": null,
        "app_name": null,
        "credential": null,
        "credential_name": null,
        "runs": 2,
        "amount": 0.04
      }
    ]
  }
}
```

The payload is wrapped in `data`. Fields:

<ResponseField name="total" type="number">
  Period total; equals the sum of group `amount` values.
</ResponseField>

<ResponseField name="currency" type="string">
  Currency.
</ResponseField>

<ResponseField name="group_by" type="string">
  Dimension actually used.
</ResponseField>

<ResponseField name="groups" type="object[]">
  Group rows. Every dimension field is present; unused ones are `null`.

  <Expandable title="fields">
    <ResponseField name="day" type="string">
      Key when `group_by=day`, `YYYY-MM-DD`.
    </ResponseField>

    <ResponseField name="namespace" type="string">
      Publisher username when `group_by=data_app`.
    </ResponseField>

    <ResponseField name="app_name" type="string">
      App name when `group_by=data_app`.
    </ResponseField>

    <ResponseField name="credential" type="string">
      Stable credential id when `group_by=credential`.
    </ResponseField>

    <ResponseField name="credential_name" type="string">
      Display name of the credential when available.
    </ResponseField>

    <ResponseField name="runs" type="integer">
      Run count in the group.
    </ResponseField>

    <ResponseField name="amount" type="number">
      Data fee total for the group.
    </ResponseField>
  </Expandable>
</ResponseField>

### Errors

| HTTP | `code`          | `category`      | Description                 |
| ---- | --------------- | --------------- | --------------------------- |
| 400  | `invalid-input` | `invalid_input` | Parameters are invalid.     |
| 401  | `unauthorized`  | `forbidden`     | Missing or invalid API key. |

Error responses use `{"error": {code, category, message, retryable}}`. See <a href="/docs/en/datahub/api/reference/introduction#errors">Errors</a>.

## Client libraries

<CodeGroup>
  ```python Python theme={null}
  print(client.billing(group_by="data_app", tz_offset=0))
  ```

  ```js JavaScript theme={null}
  console.log(await client.billing({ groupBy: "data_app", tzOffset: 0 }));
  ```
</CodeGroup>