Account

Your own usage, clients, and status.

3 POST routes read the token that called them. They are not market data. Each one is also an MCP tool, listed in tools/list for every token. Paths and tools are on API overview.

Send the same bearer token as any other route. The client_id in the response is that token’s api_user_id. Putting client_id or api_user_id in the body is 422. A disabled market group does not hide these routes: ENDPOINT_NOT_ENABLED does not apply. enabled_groups tells you which market groups this token may call.

What every call shares

• Method is POST. Another method is 405 and Allow: POST.
• An empty body needs no Content-Type. A non-empty body must be application/json. A parameter after ; is fine. Anything else is 422: Content-Type must be application/json.
• The body is one JSON object, at most 1024 bytes. Over that is 413 PAYLOAD_TOO_LARGE. Market routes use 4 KiB. The proxy still rejects any body over 64 KiB.
• An array, a string, or broken JSON is 422: Body must be a JSON object. A repeated key is 422: Duplicate field "days". with the key name. That is the same parser as a market route. A nested object is not a separate error: days still has to be an integer, and clients and status still take no fields. The 422 has an error.details array in the same form as a market route (see Errors).
• A success is ok, data, and meta.request_id. There is no data.items, no cursor, and no response cache. Age is not set.
• Timestamps are ISO 8601 with an America/New_York offset, to the second: 2026-10-20T12:31:07-04:00. No milliseconds, no Z, no bare wall time. Counts are 0, not null.

MCP tools

The arguments are the REST body; no arguments is an empty body. The answer is the same envelope in structuredContent, with isError: true on a failure. A tool call uses the same validation, the same 1024-byte cap, and the same account counter as REST: a REST call and a tool call in one minute count twice. get_account_status is the connection test; there is no separate ping. The arguments never carry the token.

Two limits

After a good auth, the shared user budget still counts. The default is 120 requests per client id per ET minute, shared with market REST and MCP. The response field rate_limit.per_minute is that number. The RateLimit-* headers are that window too. Over it, the code is RATE_LIMIT_EXCEEDED, and the account counter does not move. Headers and the other shared codes are on Rate limits and Errors.

These 3 routes then have their own counter: 30 requests per client id per ET minute (ACCOUNT_RATE_LIMIT). Over it, the HTTP status is 429 and the code is ACCOUNT_RATE_LIMITED. Retry-After is whole seconds until the next America/New_York minute, at least 1. meta.rate_limit.scope is account, remaining is 0, and reset_at is that next minute.

{
  "ok": false,
  "error": {
    "code": "ACCOUNT_RATE_LIMITED",
    "message": "Account endpoint rate limit exceeded.",
    "request_id": "req_example_01"
  },
  "meta": {
    "rate_limit": {
      "scope": "account",
      "limit": 30,
      "remaining": 0,
      "reset_at": "2026-10-20T12:32:00-04:00"
    }
  }
}

A 422 or a 413 that reaches the handler has already taken one user attempt and one account-limit slot. Neither is usage. Auth failures never reach the account counter.

curl --request POST \
  --url "${TANUKI_BASE_URL}/api/v1/account/usage" \
  --header "Authorization: Bearer ${TANUKI_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{"days":2}'

{
  "ok": true,
  "data": {
    "client_id": "ab12cd34",
    "days": 2,
    "rate_limit": {"per_minute": 120},
    "enabled_groups": ["discovery", "fundamentals", "volatility"],
    "totals": {
      "requests": 14,
      "api_requests": 11,
      "mcp_requests": 3,
      "bytes_out": 184320,
      "bytes_in": 4096
    },
    "today": {
      "date": "2026-10-20",
      "requests": 6,
      "api_requests": 4,
      "mcp_requests": 2,
      "bytes_out": 81920,
      "bytes_in": 2048,
      "by_endpoint": [
        {"operation": "list_symbols", "group": "discovery", "api": 4, "mcp": 0, "total": 4},
        {"operation": "list_volatility_iv_metrics", "group": "volatility", "api": 0, "mcp": 2, "total": 2}
      ]
    },
    "daily": [
      {
        "date": "2026-10-19",
        "requests": 8,
        "api_requests": 7,
        "mcp_requests": 1,
        "bytes_out": 102400,
        "bytes_in": 2048
      },
      {
        "date": "2026-10-20",
        "requests": 6,
        "api_requests": 4,
        "mcp_requests": 2,
        "bytes_out": 81920,
        "bytes_in": 2048
      }
    ],
    "by_endpoint": [
      {"operation": "list_symbols", "group": "discovery", "api": 9, "mcp": 0, "total": 9},
      {"operation": "list_volatility_iv_metrics", "group": "volatility", "api": 2, "mcp": 3, "total": 5}
    ],
    "as_of": "2026-10-20T12:31:07-04:00"
  },
  "meta": {"request_id": "req_example_01"}
}

curl --request POST \
  --url "${TANUKI_BASE_URL}/api/v1/account/clients" \
  --header "Authorization: Bearer ${TANUKI_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data '{}'

{
  "ok": true,
  "data": {
    "client_id": "ab12cd34",
    "first_used_at": "2026-09-01T09:15:00-04:00",
    "last_used_at": "2026-10-20T12:31:07-04:00",
    "clients": [
      {
        "transport": "api",
        "ip": "203.0.113.10",
        "user_agent": "tanuki-docs-example/1.0",
        "first_seen_at": "2026-10-01T09:15:00-04:00",
        "last_seen_at": "2026-10-20T12:31:07-04:00",
        "requests": 42
      },
      {
        "transport": "mcp",
        "ip": "203.0.113.11",
        "user_agent": "",
        "first_seen_at": "2026-09-01T09:15:00-04:00",
        "last_seen_at": "2026-10-02T16:00:00-04:00",
        "requests": 3
      }
    ],
    "as_of": "2026-10-20T12:31:07-04:00"
  },
  "meta": {"request_id": "req_example_01"}
}

curl --request POST \
  --url "${TANUKI_BASE_URL}/api/v1/account/status" \
  --header "Authorization: Bearer ${TANUKI_TOKEN}" \
  --header "Accept: application/json"

{
  "ok": true,
  "data": {
    "service": "operational",
    "data_as_of": "2026-10-20T12:30:00-04:00",
    "client_id": "ab12cd34",
    "enabled_groups": ["discovery", "fundamentals", "volatility"],
    "rate_limit": {"per_minute": 120},
    "server_time": "2026-10-20T12:31:07-04:00"
  },
  "meta": {"request_id": "req_example_01"}
}

Errors on these routes

Own-database failure on usage or clients is 503 DATA_UNAVAILABLE. Status still answers from the health check and the builder timestamp; it does not query that table. The full code list is on Errors.

TanukiTrade API and MCP. Derived options analytics for your code and for agents. Not investment advice. tanukitrade.com