# API-gebruik begrijpen

Het onderdeel **API-gebruik** laat zien welke aanvragen je organisatie heeft gedaan. De console ververst deze gegevens elke 60 seconden en gebruikt UTC voor alle tijdstippen.

## De drie totalen

| Totaal | Wat het betekent |
| --- | --- |
| API-aanvragen | Aantal geregistreerde verzoeken in de afgelopen 30 dagen. |
| Verbruikseenheden | Som van de eenheden van die verzoeken. |
| Fouten | Aantal geregistreerde verzoeken met HTTP-status 400 of hoger. |

Een succesvolle API-keyaanvraag telt normaal als één eenheid. Een fout telt als nul eenheden. Een succesvolle idempotente herhaling telt ook als nul eenheden, maar blijft een aanvraag. Zo kun je herhaalverkeer terugzien zonder dat het als nieuwe verwerking telt.

**Deze pilot registreert gebruik; er zijn nog geen tarieven, facturen, abonnementen of betaalstromen.** Een verbruikseenheid is dus nog geen bedrag.

## Recente aanvragen lezen

De lijst bevat maximaal de laatste 100 aanvragen uit de afgelopen 30 dagen.

| Kolom | Uitleg |
| --- | --- |
| Tijdstip (UTC) | Wanneer de aanvraag werd geregistreerd. |
| API-key | De herkenbare naam van de gebruikte key. |
| Endpoint | De methode en route, bijvoorbeeld `GET /account/v1/usage`. |
| HTTP-status | `200` of `201` bij succes; 400 en hoger wijst op een fout. |
| Eenheden | Het geregistreerde verbruik voor deze aanvraag. |

Routes met een ID worden als routepatroon opgeslagen, bijvoorbeeld `/parcels/{id}`. De response- of requestbody en volledige key worden niet in deze gebruikstabel opgenomen. De API-versie van de lijst bevat daarnaast `request_id` en `key_id`, handig om een fout terug te vinden.

## Verbruik per dag en endpoint

De tweede tabel groepeert alle geregistreerde aanvragen in het 30-dagenvenster per UTC-dag en route. Daarom kunnen de dagtotalen meer verzoeken bevatten dan de lijst met de laatste 100 aanvragen.

De weergave van 30 dagen is een rapportagevenster. Er is in deze pilot nog geen automatisch retentiebeleid dat alle oudere logs verwijdert.

## Wat wordt niet als gebruik geteld?

Handelingen in de console, zoals inloggen of een key aanmaken, tellen niet als API-aanvragen van je koppeling.

Een ongeldige, verlopen of ingetrokken key kan niet meer worden geauthenticeerd en wordt niet aan je organisatie toegeschreven. Onbekende routes worden ook niet als klantgebruik geregistreerd. Een geldige key die op een bekende route onvoldoende rechten heeft, levert wel een geregistreerde fout op.

## Waarom zie ik mijn eigen usage-aanvraag nog niet?

Een usage-endpoint leest eerst de bestaande gegevens en registreert daarna de huidige aanvraag. Je ziet deze aanvraag dus bij de volgende keer opvragen. Een lege eerste lijst is normaal.

## Gebruik blijft bestaan na intrekken

Het intrekken van een API-key verwijdert de historische logs niet. Zo kun je ook achteraf controleren welke aanvragen met een oude key zijn gedaan. Lees [Fouten & opnieuw proberen](/foutmeldingen/) om veelvoorkomende fouten te onderzoeken.

## Gebruiksgegevens via de API

Gebruik een key met `usage:read`. Beide aanvragen hebben alleen de `Authorization: Bearer <key>`-header nodig: geen body, organisatie-ID, datumfilters of andere queryvelden. Het venster is altijd de afgelopen 30 dagen.

```sh
curl --fail-with-body --silent --show-error \
  'https://api.vlows.io/account/v1/usage' \
  -H "Authorization: Bearer $API_KEY"
```

Bij `GET /account/v1/usage` is `data` een lijst van dagtotalen:

| Antwoordveld per item | Type en betekenis |
| --- | --- |
| `day` | RFC 3339-datumstring van het begin van de UTC-dag, bijvoorbeeld `2026-10-16T00:00:00Z`. |
| `route` | Tekst met methode en routepatroon, bijvoorbeeld `GET /deliveries/v1/parcels/{id}`. |
| `requests` | Geheel getal: aantal geregistreerde aanvragen voor die dag en route. |
| `units` | Geheel getal: som van verbruikseenheden voor die dag en route. |
| `errors` | Geheel getal: aantal aanvragen met HTTP-status 400 of hoger. |

Gebruik `GET /account/v1/usage/requests` voor de laatste maximaal 100 aanvragen binnen hetzelfde venster. Ook hier is `data` een lijst:

| Antwoordveld per item | Type en betekenis |
| --- | --- |
| `request_id` | Tekst: identificatie van de aanvraag, ook beschikbaar als `X-Request-ID` bij het antwoord op die aanvraag. |
| `created_at` | RFC 3339-datumstring van de registratie, bijvoorbeeld `2026-10-16T08:00:00Z`. |
| `key_id` | UUID van de gebruikte key; dit is niet de geheime keywaarde. |
| `key_name` | Naam die bij het aanmaken van de key is gekozen. |
| `route` | Tekst met methode en routepatroon. |
| `status` | Geheel getal: HTTP-status van de aanvraag, bijvoorbeeld 200 of 422. Dit is geen bezorgstatus. |
| `units` | Geheel getal: verbruikseenheden voor deze ene aanvraag. |

Een leeg resultaat is `{"data":[],"error":null}`. Beide endpoints tonen organisatiegegevens: de leeskey beperkt de weergave niet tot uitsluitend aanvragen die met diezelfde key zijn gedaan.