Reporting

Service usage

‘s reporting service buckets and updates consumption, success, and latency metrics at intervals of 1 hour. The service has a RESTful interface that accepts GET requests at https://‍/usage.

Authentication

You can access the service by including your secret API token in an Authorization header:

Authorization: Bearer [API token here]

Here’s an example request that uses the common Curl command:

curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/usage'\
'?from=2025-12-24'\
'&to=2025-12-25'

Report parameters

You should specify an ISO date or time range to generate a report:

curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/usage'\
'?from=2025-12-24T18:00:00-06:00'\
'&to=2025-12-25T9:00:00-06:00'

The API will return a JSON array:

[{
  "email": "user@example.com",
  "from": "2025-12-25T00:00:00+00:00",
  "to": "2025-12-25T15:00:00+00:00",
  "service": "browser",
  "result": "success",
  "calls": 17208,
  "credits": 17208,
  "meanSecs": 6.78
}, {
  "email": "user@example.com",
  "from": "2025-12-25T01:00:00+00:00",
  "to": "2025-12-25T15:00:00+00:00",
  "service": "browser",
  "result": "failure",
  "calls": 18,
  "credits": 0,
  "meanSecs": 60.22
}]

Your report can optionally be filtered by one or more services:

curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/usage'\
'?from=2025-12-24'\
'&to=2025-12-25'\
'&service=search'

View multiple-service example

curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/usage'\
'?from=2025-12-24'\
'&to=2025-12-25'\
'&service=search'\
'&service=ai'

You can also disaggregate the metrics:

curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/usage'\
'?from=2025-12-24'\
'&to=2025-12-25'\
'&by=hour'

These are the request keys and values:

Key	Required	Value
`from`	✅	The ISO datetime to select data starting from, inclusively
`to`	✅	The ISO datetime to select data up to, inclusively
`email`	⬜	[Whitelabelers only] The (case-insensitive) email address of the user to select data for; multiple email addresses can be provided by repeating the key; data for all email addresses is included by default
`service`	⬜	The service to select data for, `search`, `ai`, or `browser`; multiple services can be provided by repeating the key; data for all services is included by default
`by`	⬜	The time unit to group the data by, `hour`, `day` (planned), or `total`; `total` is the default unit

These are the response keys and values:

Key	Value
`email`	The email address of the user whose data is selected
`from`	The ISO datetime of the first datapoint
`to`	The ISO datetime of the last datapoint
`service`	The service included in the data, `search`, `ai`, or `browser`
`result`	The type of result included in the data, `success` or `failure`
`calls`	The number of API calls of the service and result type
`credits`	The number of credits consumed by the API calls
`meanSecs`	The average number of elapsed seconds of the API calls

Additional examples

Email filtering

curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/usage'\
'?from=2025-12-24'\
'&to=2025-12-25'\
'&email=alice@example.com'\
'&email=bob@example.com'\
'&email=carol@example.com'

Introduction

Core API

Shared options

API management

For service providers

Service usage

Authentication

Report parameters

Additional examples

Email filtering

​Service usage

​Authentication

​Report parameters

​Additional examples

​Email filtering

Service usage

Authentication

Report parameters

Additional examples

Email filtering