Documentation / MCP / account_usage

account_usage

POSThttps://mcp.oppalerts.com/mcptool: 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_all is true when you see every token and every call of the account, and false when you see only your own.
  • tokens lists the tokens. Each token has id, name, person, type, created_at, expires_at, and last_used_at. An empty expires_at or last_used_at means never.
  • days holds one item for each day, with day, 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, and tokens (the calls of each token, by token id). counted is the number of calls that day that used a daily call, from website, website_saves, and the calls in tokens. A refused call, for example a call with a bad field, is in its column but used no daily call, so it is not in counted. A search stopped by the index (HTTP 422) used a daily call. website_not_counted is never in counted. A token with no call that day is not in tokens. A revoked token is not in tokens: its calls show in last_calls only.
  • last_calls holds 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 has at, source (api, mcp, or website), token_id, person, route, tool, status, ms, and counted. counted is true for a call that used a daily call and false for every other call. A call that is not a call of a tool is listed with counted false: the MCP messages initialize, tools/list, and ping, a notification, a tools/call with no id, an unknown method, GET /v1/tools, and an address that is not a tool. These rows are not in counted of the day.
  • A web page call of a tool that reads the account's own data does not count, and it is listed with counted false: 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, and taxonomy_taxonomies. A call of these tools through the API or MCP counts.

All times in the response are ISO 8601 text in UTC.

Connect

claude mcp add --transport http oppalerts https://mcp.oppalerts.com/mcp

The first call opens a browser window for the OppAlerts login. Connect an AI Agent has the details.

Parameters

This tool has no parameters. Send an empty object.

Strict Rules

  • This tool accepts no fields. Any field you send is refused. The result then has isError true, and its text starts with 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

Call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "account_usage",
    "arguments": {}
  }
}

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

An error returns as a tool result with isError true. Its text starts with the error code, except for daily_limit, whose text is only the sentence. The HTTP status shown for each code is its API status.

  • bad_param (HTTP 400 in the API): the request has a field. This tool accepts no fields, and the error names the field you sent.
  • db_error (HTTP 500 in the API): the data could not be read. The sentence says which data. Try again in a few minutes.
  • daily_limit (HTTP 429 in the API): 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 data in the API

POST /v1/account/usage HTTP/1.1
Host: api.oppalerts.com
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{}

The API page is POST /v1/account/usage.