> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revalonlabs.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage Stats API — Monitor API Consumption

> Fetch aggregated usage statistics and raw request logs for your Predexy API keys. Track call volume, error rates, and per-endpoint latency.

Predexy's usage stats endpoints let you monitor how your API keys are being used. You can retrieve aggregated call counts and latency metrics by time period, or pull raw per-request logs for debugging. Both endpoints require console session authentication (`Authorization: Bearer <access_token>`).

## Get aggregated usage statistics

`GET /api/v1/console/stats` returns call volume and latency metrics aggregated by time period for a specific API key.

**Query parameters:**

<ParamField query="api_key_id" type="string" required>
  UUID of the API key to fetch statistics for. Get this from `GET /api/v1/console/keys`.
</ParamField>

<ParamField query="granularity" type="string" default="daily">
  Aggregation period. One of `hourly`, `daily`, or `monthly`.
</ParamField>

<ParamField query="limit" type="integer" default="30">
  Number of periods to return. Minimum 1, maximum 90.
</ParamField>

**Example request:**

```bash theme={null}
curl "https://api.predexy.com/api/v1/console/stats?api_key_id=YOUR_KEY_UUID&granularity=daily&limit=7" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Example response:**

```json theme={null}
{
  "data": [
    {
      "period_start": "2026-04-20T00:00:00Z",
      "total_calls": 1523,
      "successful_calls": 1500,
      "error_calls": 23,
      "avg_latency_ms": 42.5,
      "p95_latency_ms": 120.0,
      "unique_endpoints": 3
    },
    {
      "period_start": "2026-04-21T00:00:00Z",
      "total_calls": 891,
      "successful_calls": 888,
      "error_calls": 3,
      "avg_latency_ms": 38.1,
      "p95_latency_ms": 95.0,
      "unique_endpoints": 2
    }
  ],
  "meta": {
    "granularity": "daily",
    "count": 2
  }
}
```

**Response fields:**

<ResponseField name="period_start" type="string (date-time)">
  Start of the aggregation period in ISO 8601 format.
</ResponseField>

<ResponseField name="total_calls" type="integer">
  Total API requests made during the period.
</ResponseField>

<ResponseField name="successful_calls" type="integer">
  Requests that returned a 2xx status code.
</ResponseField>

<ResponseField name="error_calls" type="integer">
  Requests that returned a 4xx or 5xx status code.
</ResponseField>

<ResponseField name="avg_latency_ms" type="number">
  Average server-side response time in milliseconds.
</ResponseField>

<ResponseField name="p95_latency_ms" type="number">
  95th percentile response time in milliseconds. Useful for detecting slow outliers.
</ResponseField>

<ResponseField name="unique_endpoints" type="integer">
  Number of distinct API endpoints called during the period.
</ResponseField>

## Get raw request logs

`GET /api/v1/console/logs` returns a paginated list of individual API requests for a specific key. Use this to debug errors or audit specific calls.

**Query parameters:**

<ParamField query="api_key_id" type="string" required>
  UUID of the API key to fetch logs for.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Maximum number of log entries to return (1–200).
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of entries to skip for pagination.
</ParamField>

**Example request:**

```bash theme={null}
curl "https://api.predexy.com/api/v1/console/logs?api_key_id=YOUR_KEY_UUID&limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

**Example response:**

```json theme={null}
{
  "data": [
    {
      "endpoint": "/api/v1/external/arbitrage/opportunities",
      "method": "GET",
      "status_code": 200,
      "response_time_ms": 45,
      "created_at": "2026-04-21T14:32:01Z"
    },
    {
      "endpoint": "/api/v1/external/arbitrage/opportunities",
      "method": "GET",
      "status_code": 429,
      "response_time_ms": 5,
      "created_at": "2026-04-21T14:31:58Z"
    }
  ],
  "meta": {
    "count": 2,
    "offset": 0,
    "limit": 20,
    "total": 1523
  }
}
```

<ResponseField name="endpoint" type="string">
  The API endpoint path that was called.
</ResponseField>

<ResponseField name="method" type="string">
  HTTP method used (GET, POST, DELETE, etc.).
</ResponseField>

<ResponseField name="status_code" type="integer">
  HTTP status code returned by the server.
</ResponseField>

<ResponseField name="response_time_ms" type="integer">
  Server-side response time in milliseconds.
</ResponseField>

<ResponseField name="created_at" type="string (date-time)">
  Timestamp of the request in ISO 8601 format.
</ResponseField>

## Tips

<Tip>
  To find your API key's UUID, call `GET /api/v1/console/keys` and use the `id` field from the key you want to inspect.
</Tip>

<Note>
  Use `granularity=hourly` when debugging a sudden error spike, and `granularity=monthly` for quota planning. Switch to raw logs (`/console/logs`) to identify the exact requests causing 4xx errors.
</Note>