---
title: "API key metrics"
method: POST
path: "/api/api-keys/metrics"
tags: ["api_keys"]
---

# API key metrics

`POST /api/api-keys/metrics`

## Request

- Base URL: `https://beta.getsales.io/id/v1`
- URL: `https://beta.getsales.io/id/v1/api/api-keys/metrics`
- Auth: HTTP bearer and API key in header `Team-SID`

Period-bound counts of the team's keys: by status, plus how many were minted and how many expired inside the window (created_in_period, expired_in_period). period {from, to} is required; filter narrows the set. The status split always rides aggregated.counts.groups.status: group_by is accepted and builds no groups[]. Counts key rows, not the traffic made with them.

Contract:
- MCP tool `get_api_keys_metrics`, registry package `mcp.id/api_keys`, mount `id.access`.
- Operation `metrics`, response envelope `metrics`.
- Flags: read only.

## Request body

- GetApiKeysMetricsRequest: Request body of `get_api_keys_metrics`.
  - `filter` object: Scopes the rows the metrics are computed over: the search filter operators. Omit for all rows.
    - `sid` object: Key sid(s).
      - `eq` string
      - `in` string[]
    - `status` object: active | revoked | expired.
      - `eq` 'active' | 'revoked' | 'expired'
      - `ne` 'active' | 'revoked' | 'expired'
      - `in` string[]
      - `nin` string[]
    - `name` object: Exact name.
      - `eq` string
    - `created_by_actor_sid` object: Keys a teammate (us_mb_) or a parent key (id_ak_) issued: the offboarding slice.
      - `eq` string
      - `in` string[]
    - `expires_at` object: is_null true = perpetual keys; a range = expiring between.
      - `gte` string
      - `lte` string
      - `gt` string
      - `lt` string
      - `is_null` boolean
    - `last_used_at` object: is_null true = never used; lt = stale keys.
      - `gte` string
      - `lte` string
      - `gt` string
      - `lt` string
      - `is_null` boolean
    - `created_at` object: ISO 8601 bounds.
      - `gte` string
      - `lte` string
      - `gt` string
      - `lt` string
    - `deleted_at` object: Default scope is { is_null: true } (live rows).
      - `gte` string
      - `lte` string
      - `is_null` boolean
  - `period` object, required: Required metrics window.
    - `from` string, required: ISO 8601 UTC window start (inclusive).
    - `to` string, required: ISO 8601 UTC window end; at or after from.
  - `group_by` 'status', nullable: Accepted for the shared contract and not split on: the status split always rides aggregated.counts.groups.status; no groups[] is built.

## Response `200`

`metrics` success envelope.

- GetApiKeysMetricsResponse
  - `success` true, required
  - `operation` 'metrics', required
  - `metrics` object, required
    - `filter` object
    - `period` object
      - `from` string, required
      - `to` string, required
    - `aggregated` object
      - `counts` object
      - `metrics` object
        - `created_in_period` number, required: Keys minted inside the window.
        - `expired_in_period` number, required: Keys that expired inside the window.
        - `last_used_at` string, nullable, required: The most recent verified call across the set; null = none.
    - `metrics` object
      - `created_in_period` number, required: Keys minted inside the window.
      - `expired_in_period` number, required: Keys that expired inside the window.
      - `last_used_at` string, nullable, required: The most recent verified call across the set; null = none.
  - `applied_filters` object
  - `meta` object, required
    - `trace_id` string, required: UUID v7; same 128-bit value as the X-Trace-Id header.
    - `span_id` string, required: 16 hex chars, root span of this request.
    - `timestamp` string, required: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
    - `duration_ms` integer, required: Server-side wall clock.
    - `team_sid` string, nullable: The team this call ran in (the token team, or the team_sid override). Null when unauthenticated; absent from pre-2026-08-20 backends.
    - `actor_type` string, nullable: user | agent | api_key | system. Null when unauthenticated; absent from pre-2026-08-20 backends.

## Other responses

- `4XX`: MCP error envelope. `error.code` is one of validation_failed, nothing_to_update, not_found, relation_not_found, invalid_transition, limit_exceeded, payment_required, duplicate_rejected, conflict, delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
- `5XX`: MCP error envelope with `error.code` internal_error or service_unavailable.

---

[API](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id.md) - [All operations](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/llms.txt) - [OpenAPI document](https://skmtc.dev/getsales/apis/getsales-public-contract-gs-service-id/revisions/95e48541fe85?raw)