> ## 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.

# Aggregazione fatturazione

> Somma la spesa su un periodo e suddividila per giorno, app o credenziale.

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

Autenticazione: API key obbligatoria (`Authorization: Bearer <API Key>`).

Quanto hai speso in un periodo, e dove. Indipendente dall’endpoint identity account.

L’intervallo temporale usa lo stesso vocabolario di <a href="/docs/it/datahub/api/reference/runs/list-runs">Elenca esecuzioni</a>: `created_from` / `created_to` sono orari assoluti ISO-8601 inclusivi/esclusivi chiave sull’ora di **start** della run. Passa gli stessi bound a Elenca esecuzioni per fare drill-down sulle run dietro ogni totale di gruppo. `tz_offset` decide solo in quale giorno locale cade una run per i bucket giorno; non cambia importi né il range assoluto.

Solo le data fee sono aggregate. I gruppi giorno salgono per reconciliation; i gruppi app e credential scendono per importo così la spesa maggiore compare prima.

La suddivisione `credential` risponde a “quanto ha speso ciascuna key?”. La key è un id credenziale stabile non sensibile, lo stesso del filtro `credential` di Elenca esecuzioni. Scope sempre il tuo account; mai le credenziali altrui.

## Richiesta

### Parametri di query

<ParamField query="group_by" type="string" default="day">
  Dimensione di ripartizione: `day` (predefinito), `data_app` o `credential`.
</ParamField>

<ParamField query="created_from" type="string">
  Inizio inclusivo. Ometti per partire dalla run più remota.
</ParamField>

<ParamField query="created_to" type="string">
  Fine esclusiva. Ometti per includere fino a ora.
</ParamField>

<ParamField query="tz_offset" type="integer" default="0">
  Offset di fuso orario dei bucket giornalieri, in minuti rispetto a UTC. Usa `480` per l'ora standard della Cina; il valore predefinito `0` corrisponde ai giorni UTC. Solo offset fisso (niente ora legale). Le query di dettaglio con `created_from` / `created_to` devono usare lo stesso offset. Intervallo da -720 a 840.
</ParamField>

### Esempio di richiesta

```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"
```

## Risposta

### 200 successo

```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
      }
    ]
  }
}
```

Il payload è wrappato in `data`. Campi:

<ResponseField name="total" type="number">
  Totale del periodo; è uguale alla somma dei valori `amount` dei gruppi.
</ResponseField>

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

<ResponseField name="group_by" type="string">
  Dimensione effettivamente usata.
</ResponseField>

<ResponseField name="groups" type="object[]">
  Righe di gruppo. Ogni campo di dimensione è presente; quelli non usati valgono `null`.

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

    <ResponseField name="namespace" type="string">
      Username publisher quando `group_by=data_app`.
    </ResponseField>

    <ResponseField name="app_name" type="string">
      Nome app quando `group_by=data_app`.
    </ResponseField>

    <ResponseField name="credential" type="string">
      ID credenziale stabile quando `group_by=credential`.
    </ResponseField>

    <ResponseField name="credential_name" type="string">
      Nome visualizzato della credenziale se disponibile.
    </ResponseField>

    <ResponseField name="runs" type="integer">
      Conteggio run nel gruppo.
    </ResponseField>

    <ResponseField name="amount" type="number">
      Totale dei costi dei dati del gruppo.
    </ResponseField>
  </Expandable>
</ResponseField>

### Errori

| HTTP | `code`          | `category`      | Descrizione                    |
| ---- | --------------- | --------------- | ------------------------------ |
| 400  | `invalid-input` | `invalid_input` | I parametri non sono validi.   |
| 401  | `unauthorized`  | `forbidden`     | API key mancante o non valida. |

Le risposte di errore usano `{"error": {code, category, message, retryable}}`. Vedi <a href="/docs/it/datahub/api/reference/introduction#errors">Errori</a>.

## Librerie client

<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>