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

# Hämta aggregerad statistik över API-anropsvolym för AceDataCloud-plattformen

> Platform API guide - Ace Data Cloud

Sammanställ antalet begäranden och faktiskt avdragen kvot för det aktuella kontot efter datum och API, lämpligt för att skapa månadsrapporter, trenddiagram och kostnadsanalyser. Använd [lista över anropsposter](https://platform.acedata.cloud/documents/platform-usage-list) när du behöver felsöka rad för rad, och använd [export av anropsvolym](https://platform.acedata.cloud/documents/platform-usage-export) när du behöver fullständiga offline-detaljer.

## Förberedelser

1. Logga in på [AceDataCloud-plattformen](https://platform.acedata.cloud).
2. Skapa en kontotoken i [Account Token-konsolen](https://platform.acedata.cloud/console/platform-tokens), och spara den omedelbart.
3. Om du behöver begränsa omfattningen, hämta motsvarande ID från [listan över tjänsteansökningar](https://platform.acedata.cloud/documents/platform-application-list), [listan över API-autentiseringsuppgifter](https://platform.acedata.cloud/documents/platform-credential-list) eller [API-listan](https://platform.acedata.cloud/documents/platform-api-list).

Fullständig beskrivning av token finns i [Hantera kontotoken](https://platform.acedata.cloud/documents/platform-token). Detta gränssnitt använder Account Token, inte verksamhets-Credential.

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
```

## Gränssnittsöversikt

| Objekt | Innehåll |
| - | - |
| Metod | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/aggregate/` |
| Autentisering | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read`（`platform:read` / `platform` kan utökat inkludera） |
| Behörighetsomfång | Vanliga användare är begränsade till sin egen betalda användning; administratörer kan ange `user_id` |

## Frågeparametrar

| Parameter | Typ | Obligatorisk | Standard | Beskrivning |
| - | - | - | - | - |
| `created_at_from` | date / datetime | Nej | Den första dagen i aktuell månad i vald tidszon | Starttid, rekommenderat parameternamn |
| `created_at_to` | date / datetime | Nej | Aktuell tid | Sluttid, rekommenderat parameternamn |
| `timezone` | string | Nej | `UTC` | IANA-tidszon, till exempel `Asia/Shanghai`; ogiltiga värden återgår till UTC |
| `service_id` | UUID | Nej | — | Filtrera efter tjänst; upprepade parametrar stöds |
| `application_id` | UUID | Nej | — | Filtrera efter Application; upprepade parametrar stöds |
| `api_id` | UUID | Nej | — | Filtrera efter API; upprepade parametrar stöds |
| `credential_id` | UUID | Nej | — | Filtrera efter API-autentiseringsuppgift; upprepade parametrar stöds |
| `include_models` | boolean | Nej | `false` | Om sammanställning per modelldimension också ska beräknas; ökar frågekostnaden |
| `user_id` | UUID | Nej | Vanliga användare är begränsade till sig själva; om administratörer inte anger detta omfattas alla konton | Endast administratörer kan ange valfritt konto |

`start_time` / `end_time` kan fortfarande användas som kompatibilitetsalias för äldre klienter, nya integrationer använder enhetligt `created_at_from` / `created_at_to`. Datumformatet för `created_at_to` inkluderar den aktuella kalenderdagen, det vill säga midnatt nästa dag används som gräns.

## Begäransexempel

Fråga daglig/API-sammanställning för innevarande månad i Pekingtid, och inkludera modelldimensionen:

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  --data-urlencode 'include_models=true' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Fråga en veckas användning för en angiven Application:

```shell theme={null}
export APPLICATION_ID='你的 Application ID'

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01' \
  --data-urlencode 'created_at_to=2026-09-07' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Python-exempel:

```python theme={null}
import os
import requests

response = requests.get(
    "https://platform.acedata.cloud/api/v1/usage/apis/aggregate/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "created_at_from": "2026-09-01",
        "created_at_to": "2026-09-07",
        "timezone": "Asia/Shanghai",
        "include_models": "true",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
print("requests:", data["requests"], "deducted:", data["total"])
for row in data["items"]:
    print(row["date"], row["api_id"], row["amount"])
```

## Svarsexempel

```json theme={null}
{
  "items": [
    {
      "date": "2026-09-01",
      "api_id": "00000000-0000-4000-8000-000000000001",
      "amount": 12.5
    }
  ],
  "total": 12.5,
  "apis": {
    "00000000-0000-4000-8000-000000000001": {
      "title": "Example API"
    }
  },
  "requests": 42,
  "models": [
    {
      "model": "example-model",
      "amount": 12.5,
      "requests": 42
    }
  ]
}
```

## Svarsfält

| Fält | Beskrivning |
| - | - |
| `items` | Grupperat efter datum i vald tidszon och `api_id`; varje rad innehåller `date`, `api_id`, `amount` |
| `total` | Summan av `deducted_amount` inom frågeomfånget |
| `apis` | Mappning från API-ID till titelsammanfattning, för enkel visning av `items` |
| `requests` | Totalt antal begäranden inom frågeomfånget |
| `models` | Beräknas endast när `include_models=true`; varje post innehåller `model`, `amount`, `requests` |

Kvotenheten beror på `service.unit` för den relaterade Application. Om frågan omfattar tjänster med olika enheter, gör först separata beräkningar efter `service_id` eller `application_id` för att undvika direkt jämförelse eller addition.

När sluttiden inte är senare än starttiden returnerar gränssnittet en komplett tom struktur: `items=[]`, `total=0`, `apis={}`, `requests=0`, `models=[]`.

## Fel och prestandarekommendationer

| HTTP | `error` | Åtgärd |
| - | - | - |
| 400 | `usage_history_expired` | Justera tidsintervallet till efter `available_from` i svaret |
| 401 | `not_authenticated` | Kontrollera Account Token, använd inte felaktigt verksamhets-Credential |
| 403 | `permission_denied` | Vanliga användare kan inte fråga andra konton |

* Aktivera inte `include_models` som standard; aktivera det endast när rapporten verkligen kräver modelluppdelning.
* För frågor över stora intervall, dela i första hand upp efter `service_id` eller `application_id`, vilket både undviker blandade enheter och minskar frågekostnaden.
* Datum utan anrop fylls inte automatiskt med nollor; klienten fyller i datumaxeln före diagramritning.

## Nästa steg

* [Visa anropshistorik](https://platform.acedata.cloud/documents/platform-usage-list)：identifiera detaljerna som utgör det aggregerade resultatet.
* [Exportera anropsvolym](https://platform.acedata.cloud/documents/platform-usage-export)：ladda ner fullständiga CSV-detaljer.
* [Visa detaljer för tjänsteansökan](https://platform.acedata.cloud/documents/platform-application-detail)：bekräfta saldo och enhet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.