Usage and audit events

Use usage to answer “How much did this app use?” Use audit events to answer “What happened on this exact request?”

Usage is best for totals, trends, failures, latency, and Agent Credits. Audit events are best for support and investigation. Neither includes API secrets, connection credentials, wallet keys, request inputs, or service outputs.

Read a usage summary

const response = await hive.usage.get({
  since: "2026-08-01T00:00:00.000Z",
  until: "2026-09-01T00:00:00.000Z",
  serviceId: "hive-research",
});

if (!response.ok) throw new Error(response.error);
console.log(response.usage.requests, response.usage.chargedCredits);

The summary includes total requests, failures, charged credits reported by authoritative managed services, average duration, and the same values grouped by operation id. Filter with since, until, serviceId, or operationId.

Credits are recorded only when the owning service or Platform operation returns an authoritative charge. A zero value means no charge was reported for that request; it does not turn a paid service into a free service. Use the service price catalog and account credit history for billing reconciliation.

Read audit events

const response = await hive.usage.auditEvents({
  operationId: "services.invoke.hive-research.analyses.create",
  limit: 100,
});

Each event includes:

• event id and time;
• project and API-key id;
• exact operation and managed service;
• HTTP method and public Platform path;
• final response status and duration; and
• authoritative charged credits when reported.

Audit events never include the API-key secret, credit credential, connection credential values, wallet key material, request input, or managed-service output.

Project and key boundaries

usage:read and audit:read are separate scopes. A project-bound key reads only its project. An account-level key must select a project with X-HivemindOS-Project when it wants a project-specific view.

Give audit access to operator and support workloads, not ordinary execution workers. Combine these records with webhook delivery receipts when tracing an asynchronous action from request to final event.

Next: projects and isolation, runs and webhook receipts, or per-operation limits.