Skip to main content
See also the API reference for more detail.

​
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'
This endpoint is rate limited; if you receive a 429 response, pause for the backoff time required by the Retry-After header before making another request.

​
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,
  "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,
  "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'

curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/usage'\
'?from=2025-12-24'\
'&to=2025-12-25'\
'&service=search'\
'&service=browser'
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:
KeyRequiredValue
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 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:
KeyValue
emailThe email address of the user whose data is selected
fromThe ISO datetime of the first datapoint
toThe ISO datetime of the last datapoint
serviceThe service included in the data, search or browser
resultThe type of result included in the data, success or failure
callsThe number of API calls of the service and result type
meanSecsThe 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'