---
title: "Get detailed usage statistics"
method: GET
path: "/api/v1/usage/stats"
tags: ["Usage Statistics"]
---

# Get detailed usage statistics

`GET /api/v1/usage/stats`

Retrieves hourly aggregated usage statistics for your API key within a specified date range.
            Returns detailed breakdown of requests, quota consumption, and performance metrics.

            **Authorization:** Requires valid API key.

            **Example usage:**
            ```
            GET /api/v1/usage/stats?api_key=YOUR_KEY&start_date=2025-11-01T00:00:00Z&end_date=2025-11-04T00:00:00Z&api_type=IP
            ```

## Query parameters

- `api_key` string, required
- `start_date` string, date-time, required
- `end_date` string, date-time, required
- `api_type` 'IP' | 'ADVANCED_EMAIL_VALIDATION'

## Response `200`

Successfully retrieved usage statistics

- ApiUsageStatsModel
  - `id` integer, nullable
  - `apiKey` string, required
  - `planId` string, required
  - `apiType` string, required
  - `authType` string, required
  - `hourBucket` string, date-time, required
  - `totalRequests` integer, required
  - `successfulRequests` integer, required
  - `rateLimitedRequests` integer, required
  - `quotaConsumed` integer, required
  - `peakRemainingQuota` integer, nullable
  - `minRemainingQuota` integer, nullable
  - `batchOperations` integer, required
  - `batchTokensConsumed` integer, required
  - `avgRequestDurationNanos` integer, nullable
  - `createdAt` string, date-time, nullable
  - `updatedAt` string, date-time, nullable

## Other responses

- `400` — Invalid date range or parameters
- `401` — Invalid or missing API key

---

[API](https://skmtc.dev/ip-api/apis/ip-api-io-ip-geolocation-security-api.md) · [All operations](https://skmtc.dev/ip-api/apis/ip-api-io-ip-geolocation-security-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ip-api/ip-api-io-ip-geolocation-security-api/revisions/a6862f586bf3/schema)