Documentation / API / account_usage
account_usage
POSThttps://api.oppalerts.com/v1/account/usage
The account’s calls in the last 14 days: the tokens that read the account, daily calls by source, and the most recent calls.
What it does
The tool returns the data from the account’s Usage page: the tokens that read the account, daily calls by source, and the most recent calls. It covers the last 14 days. A day runs from 04:00 to 04:00 New York time, matching the daily limits. It takes no parameters.
The account owner, an account editor, and an account viewer see every token and every call. A campaign editor and a campaign viewer see only their own tokens and calls.
The response has these parts:
sees_allistruewhen you see every token and every call of the account, andfalsewhen you see only your own.tokenslists the tokens. Each token hasid,name,person,type,created_at,expires_at, andlast_used_at. An emptyexpires_atorlast_used_atmeans never.daysholds one item for each day, withday,website(the calls of the web pages that count against the daily limits),website_saves(the changes saved on the web pages, which count too),website_not_counted(the calls of the web pages that do not count),counted, andtokens(the calls of each token, by token id).countedis the number of calls that day that used a daily call, fromwebsite,website_saves, and the calls intokens. A refused call, for example a call with a bad field, is in its column but used no daily call, so it is not incounted. A search stopped by the index (HTTP 422) used a daily call.website_not_countedis never incounted. A token with no call that day is not intokens. A revoked token is not intokens: its calls show inlast_callsonly.last_callsholds the newest 20 calls of each token, of each person's website calls that count, and of each person's website calls that do not count, newest first. Each call hasat,source(api,mcp, orwebsite),token_id,person,route,tool,status,ms, andcounted.countedistruefor a call that used a daily call andfalsefor every other call. A call that is not a call of a tool is listed withcountedfalse: the MCP messagesinitialize,tools/list, andping, a notification, atools/callwith no id, an unknown method,GET /v1/tools, and an address that is not a tool. These rows are not incountedof the day.- A web page call of a tool that reads the account's own data does not count, and it is listed with
countedfalse:campaigns_list,campaigns_settings,campaigns_organizations,campaigns_saved_opportunities,campaigns_dashboard,account_usage,account_team_members,account_calls_left,llm_answers_content_phrases,llm_answers_search_keywords,llm_answers_top_sites, andtaxonomy_taxonomies. A call of these tools through the API or MCP counts.
All times in the response are ISO 8601 text in UTC.
Authentication
Send a token in the Authorization: Bearer header. Authentication and Limits explains the tokens.
Parameters
This tool has no parameters. Send an empty object.
Strict Rules
- This tool accepts no fields. Any field you send is refused. The answer is HTTP 400 with the error code
bad_param. The error names the field: "<field> is not a field of this tool." - An error about the format of a call, such as a refused field, names the field. Its message ends with one sentence: "Read the documentation at https://oppalerts.com/docs for the correct format." Every other error has only its own sentence.
Example
Request
curl -X POST https://api.oppalerts.com/v1/account/usage \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
Response
The full sample answer.
{
"sees_all": true,
"tokens": [
{
"id": 41,
"name": "Claude Code",
"person": "Pat Example",
"type": "api_token",
"created_at": "2026-11-01T15:04:05Z",
"expires_at": "2027-01-30T15:04:05Z",
"last_used_at": "2026-11-10T14:00:00Z"
}
],
"days": [
{
"day": "2026-11-10",
"website": 12,
"website_saves": 2,
"website_not_counted": 9,
"counted": 44,
"tokens": {
"41": 30
}
}
],
"last_calls": [
{
"at": "2026-11-10T14:00:00Z",
"source": "mcp",
"token_id": 41,
"person": "Pat Example",
"route": "tools/call",
"tool": "news_search",
"status": 200,
"ms": 640,
"counted": true
}
]
}
Errors
bad_param(HTTP 400): the request has a field. This tool accepts no fields, and the error names the field you sent.db_error(HTTP 500): the data could not be read. The sentence says which data. Try again in a few minutes.daily_limit(HTTP 429): the account has used all its calls for this tool today. account_calls_left shows when the count resets.
This tool has its own daily count. A call through the API or MCP uses one call from this count. A web app page reading the same data does not count. It is not an index search, so it does not use the shared count of the news_ and prospects_ tools, and the error one_at_a_time does not apply to it.
Same tool in MCP
The MCP tool is account_usage. Read the MCP page.