---
title: "Get Endpoints Usage"
method: GET
path: "/v1/usage"
tags: ["Usage", "v1"]
---

# Get Endpoints Usage

`GET /v1/usage`

Access usage statistics for various API endpoints for monitoring and auditing purposes.
Returns usage data for all endpoints accessible by the requesting account within the specified date range.


:::info
Requires the `usage:read` OAuth2 scope.
:::

## Query parameters

- `account_id` string, required
- `start_period` string, required
- `end_period` string, required

## Response `200`

Success

- object
  - `data` ApiUsageV1[], required
    - `type` 'api_usage', required — The type of the object
    - `id` string, required — The unique identifier for the API usage record.
    - `attributes` object, required
      - `period` string, required — The period for which usage is reported, formatted as YYYY-MM
      - `endpoint_path` string, required — The API endpoint URL
      - `num_requests` integer, required — Total number of requests returned 200 SUCCESS
      - `num_failed_requests` integer, required — Total number of requests resulting in a non-200 SUCCESS response
      - `num_successful_requests` integer, required — Number of successful requests — for credit-based endpoints, this counts only when a credit is consumed; for IP endpoints, this counts only when a company match or IP data are returned.
      - `num_returned_entities` integer, required — Number of entities returned as part of successful requests.
      - `last_accessed_at` string, date-time — The timestamp when this endpoint was last accessed, in ISO8601 format
      - `http_method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' — The HTTP method used for this endpoint.
  - `meta` object, required
    - `total_records` integer, required — The total number of records in the response.
    - `request_id` string, required — A unique identifier assigned to each API request for end-to-end traceability.

## Other responses

- `400` — Invalid parameters or validation errors
- `401` — Unauthorized. The request was rejected because the credentials are missing, invalid, expired, or have been revoked. The client must re-authenticate before retrying. Clients can differentiate via the `code` value of the first item in `errors`.
- `403` — Forbidden. The credentials are valid but the caller is not authorized to perform the request — typically because the user lacks the required permission, the OAuth scope is insufficient, the subscription plan does not include the required entitlement, the `account_id` does not belong to the authenticated user, or the target list is read-only and its members cannot be modified. Clients can differentiate via the `code` value of the first item in `errors`.
- `429` — Too many requests. Either the per-second rate limit or the monthly quota configured for the API key / OAuth application has been exceeded. Clients can differentiate via the `code` value of the first item in `errors`.
- `500` — Internal server error
- `504` — Server timeout

---

[API](https://skmtc.net/leadfeeder/apis/leadfeeder-public-api.md) · [All operations](https://skmtc.net/leadfeeder/apis/leadfeeder-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/leadfeeder/leadfeeder-public-api/revisions/9e2e63ba2a4e/schema)