Wil je weten wie er vanuit het buitenland inlogde, hoeveel opslag elke gebruiker verbruikt, of welke bestanden extern gedeeld zijn? De Reports API geeft je toegang tot de audit-logs en gebruiksstatistieken van je hele organisatie. Dit is onmisbaar voor security-monitoring, compliance en capaciteitsplanning.
In dit artikel haal je beide soorten rapporten op en leg je een basis voor monitoring.
Twee soorten rapporten
De Reports API kent twee hoofdcategorieen die je los gebruikt.
- Activity reports: gedetailleerde gebeurtenissen per applicatie. Denk aan logins, admin-acties, Drive-deelacties en Gmail-instellingen. Elke regel is een gebeurtenis met actor, tijd en details.
- Usage reports: geaggregeerde cijfers per gebruiker, per klant of per entiteit. Denk aan opslaggebruik, aantal verstuurde mails of actieve apps.
Audit-data loopt iets achter
De meeste log-events (login, drive, admin, gmail) verschijnen binnen enkele minuten. Sommige bronnen lopen langer achter: token-events en OAuth tot enkele uren, en geaggregeerde rapporten doorgaans een tot drie dagen. Houd hier rekening mee bij monitoring; voor echte realtime-signalen gebruik je liever de Alert Center API of Pub/Sub.
Activity-logs ophalen
Je vraagt activiteiten op per applicationName, zoals login, drive, admin of token. De aanroep loopt via een service-account dat een beheerder impersoneert, met de scope admin.reports.audit.readonly.
response = service.activities().list(
userKey='all',
applicationName='login',
startTime='2026-05-01T00:00:00Z'
).execute()
for activiteit in response.get('items', []):
print(activiteit['actor']['email'], activiteit['events'])
Filter op eventName scheelt enorm in volume
Gebruik de parameter eventName om alleen relevante gebeurtenissen op te halen, bijvoorbeeld login_failure. Dat verkleint de respons fors en maakt je monitoring veel scherper dan alle events doorploegen. Combineer het met startTime en endTime om het tijdvak strak te houden.
Een veelgebruikt scenario: verdachte logins
Een klassieke toepassing is het detecteren van mislukte of verdachte inlogpogingen.
Verdachte logins opsporen
- Vraag
activities().listop metapplicationName='login'eneventName='login_failure'. - Groepeer de resultaten per actor en per IP-adres.
- Markeer accounts met veel mislukte pogingen of logins vanaf onbekende locaties.
- Stuur een melding naar je security-team of trigger een automatische actie, bijvoorbeeld het tijdelijk uitschakelen van een account.
- Draai dit periodiek via een geplande taak en bewaar het laatste tijdstip zodat je alleen nieuwe events ophaalt.
Usage-rapporten ophalen
Voor kwantitatieve cijfers gebruik je userUsageReport of customerUsageReport. Hiervoor heb je de scope admin.reports.usage.readonly nodig.
response = service.userUsageReport().get(
userKey='all',
date='2026-05-28'
).execute()
Elke gebruiker krijgt een set parameters terug, zoals accounts:used_quota_in_mb voor opslagverbruik.
Vraag altijd een datum in het verleden op
Usage-rapporten gaan over een specifieke afgesloten dag, niet over vandaag. Vraag een datum van enkele dagen geleden op om zeker te zijn dat de data compleet is, anders krijg je lege of onvolledige resultaten.
Naar een monitoring-pipeline
Voor serieuze monitoring exporteer je de data, omdat de console maar een beperkt venster toont. De standaard bewaartermijn voor de meeste audit-logs is zes maanden, met uitzonderingen zoals Vault (onbeperkt) en Chrome-rapporten (twaalf maanden). Via de API opgehaalde gebruiksdata per klant of gebruiker bewaart Google vijftien maanden.
Veel organisaties sturen audit-logs daarom door naar BigQuery. Daar bewaar je ze langer dan de standaardtermijn, combineer je events met andere bronnen en bouw je dashboards in Looker Studio voor je security- en compliance-team. Een veelgebruikt patroon is een geplande Cloud Function die dagelijks de nieuwe activiteiten ophaalt en wegschrijft naar een BigQuery-tabel.
Begin klein, schaal daarna op
Start met een enkel rapport, bijvoorbeeld login-events naar een tabel. Zodra dat stabiel draait voeg je drive- en admin-events toe. Zo houd je de pipeline overzichtelijk en debug je makkelijker.
Veelgestelde vragen
Welke scope heb ik nodig?
Voor alleen-lezen audit-data gebruik je admin.reports.audit.readonly. Voor usage-rapporten gebruik je admin.reports.usage.readonly. Beide zijn beperkt tot een beheerder die je via domain-wide delegation impersoneert.
Hoe ver terug gaan de logs?
De meeste audit-logs bewaart Google zes maanden. Vault-events blijven onbeperkt bewaard en Chrome-rapporten twaalf maanden. Via de API opgehaalde gebruiksdata per klant of gebruiker gaat tot vijftien maanden terug. Wil je langer bewaren, exporteer dan naar BigQuery of Cloud Logging.
Kan ik realtime alerts krijgen?
De Reports API is pull-gebaseerd en kent enige vertraging. De meeste log-events verschijnen binnen minuten, maar voor echte realtime-signalen gebruik je de Alert Center API of stuur je events via Pub/Sub.
Welke applicaties kan ik opvragen?
Onder andere login, admin, drive, token, calendar, groups, gmail, chat en mobile. Elke applicatie heeft eigen event-types die je met eventName verder filtert.
Waarom krijg ik een 403-fout?
Meestal ontbreekt de juiste scope of impersoneert je service-account geen beheerder met leesrechten op rapporten. Controleer de domain-wide delegation in de Admin console en of de geimpersoneerde gebruiker de rol Reports of een hogere admin-rol heeft.
Met de Reports API krijg je diepgaand inzicht in wat er in je organisatie gebeurt, de basis voor proactieve security en compliance.