---
title: "Get your API key's usage"
method: GET
path: "/v1/me/usage"
tags: ["Account", "tier:free"]
---

# Get your API key's usage

`GET /v1/me/usage`

## Request

- Base URL: `https://api.particle.pro`
- URL: `https://api.particle.pro/v1/me/usage`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Returns the requests this API key made in the current billing period (or today), broken down by endpoint and MCP tool, with how many bill per call. Free. Counts come from the request log, which keeps 90 days. MCP calls made through an OAuth grant are not attributed to any key.

## Query parameters

- `period` 'current' | 'today': current: the organization's billing period (the UTC calendar month without a subscription). today: the current UTC day.

## Response `200`

OK

- KeyUsage
  - `api_key` APIKey, required
    - `created_at` string, date-time, required: When the key was created
    - `created_by` Creator
      - `id` string, required: Creator's user ID
      - `name` string, required: Creator's display name
    - `expires_at` string, date-time: When the key expires, if set
    - `id` string, required: Unique identifier
    - `key_prefix` string, required: Masked key prefix for identification (e.g. pp_abc12345...)
    - `last_used_at` string, date-time: When the key was last used to authenticate a request
    - `name` string, required: Human-readable key name
  - `billable_requests` integer, required: Requests this key made that bill per call: successful calls to priced endpoints, and calls to paid MCP tools, which are metered when the call starts and so count even when the tool then fails or is denied. Free endpoints such as /v1/me are never counted, nor are endpoints and MCP tools billed through plan features rather than per call (alerts, the episode archive and stream), nor a retried write answered from its first response under an Idempotency-Key.
  - `endpoints` KeyUsageEndpoint[], nullable, required: Usage by endpoint and MCP tool, busiest first, at most 100 rows.
    - `billable_requests` integer, required: Requests in the period that bill per call.
    - `endpoint` string, required: The route template, e.g. /v1/podcasts/{id}, or /mcp for MCP tool calls.
    - `errors` integer, required: Requests that returned 400 or above.
    - `mcp_tool` string: The MCP tool the requests ran. Calls made through particle_call are credited to the tool they dispatched.
    - `method` string, required: HTTP method.
    - `requests` integer, required: Requests in the period.
  - `endpoints_truncated` boolean, required: True when the key called more endpoints than endpoints lists. The totals above still cover all of them unless totals_partial is set.
  - `errors` integer, required: Requests that returned an HTTP status of 400 or above.
  - `period` UsagePeriod, required
    - `counts_since` string, date-time: Present when the period starts more than 90 days ago, the request log's retention. Request counts cover only counts_since to now.
    - `end` string, date-time, required: End of the period (exclusive).
    - `name` 'current' | 'today', required: The period asked for.
    - `source` 'billing_period' | 'calendar_month' | 'calendar_month_fallback' | 'utc_day', required: Where start and end came from. billing_period: the organization's current billing period. calendar_month: the UTC calendar month, for an organization without an active subscription. calendar_month_fallback: the UTC calendar month because billing data could not be reached, so the billing period may differ. utc_day: the current UTC day.
    - `start` string, date-time, required: Start of the period.
  - `requests` integer, required: Requests this key made in the period, including failed and free ones.
  - `totals_partial` boolean, required: True in the rare case a key called more distinct endpoints, tools and unrouted paths than one report reads (5,000). requests still counts every request, but billable_requests and errors then cover only the busiest 5,000 of them.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/particle/apis/particle-api.md) · [All operations](https://skmtc.dev/particle/apis/particle-api/llms.txt) · [OpenAPI document](https://skmtc.dev/particle/apis/particle-api/revisions/416ba82ab9d7?raw)