> ## 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.

# Monitor API Usage with Arbitrage Analytics

> Track call volume, error rates, and response latency for each API key using aggregated usage statistics and paginated raw request logs.

Arbitrage provides two endpoints for understanding how your API keys are being used: an aggregated statistics endpoint that groups calls into time periods, and a raw log endpoint that lets you inspect individual requests. Both require your console session token and the UUID of the API key you want to inspect. You can find the UUID in the [list keys response](/console/api-keys#listing-your-keys).

## Usage statistics

`GET /api/v1/console/stats` returns call counts and latency metrics grouped by a time period you choose. Use this to spot trends — a sudden spike in error calls, a latency regression, or unusual traffic patterns.

**Query parameters:**

| Parameter     | Required | Default | Notes                                              |
| ------------- | -------- | ------- | -------------------------------------------------- |
| `api_key_id`  | Yes      | —       | UUID of the API key to fetch stats for             |
| `granularity` | No       | `daily` | One of `hourly`, `daily`, or `monthly`             |
| `limit`       | No       | `30`    | Number of periods to return. Minimum 1, maximum 90 |

```bash theme={null}
curl "https://api.predexy.com/api/v1/console/stats?\
api_key_id=3fa85f64-5717-4562-b3fc-2c963f66afa6\
&granularity=daily\
&limit=7" \
  -H "Authorization: Bearer <your-access-token>"
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "period_start": "2026-04-25T00: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-24T00:00:00Z",
      "total_calls": 891,
      "successful_calls": 891,
      "error_calls": 0,
      "avg_latency_ms": 38.1,
      "p95_latency_ms": 95.0,
      "unique_endpoints": 2
    }
  ],
  "meta": {
    "granularity": "daily",
    "count": 2
  }
}
```

**Response fields (`UsageStatPoint`):**

| Field              | Description                                                      |
| ------------------ | ---------------------------------------------------------------- |
| `period_start`     | Start of the aggregation period (ISO 8601)                       |
| `total_calls`      | All API calls made in this period                                |
| `successful_calls` | Calls that returned a 2xx status                                 |
| `error_calls`      | Calls that returned a 4xx or 5xx status                          |
| `avg_latency_ms`   | Mean server-side response time in milliseconds                   |
| `p95_latency_ms`   | 95th percentile response time — useful for catching tail latency |
| `unique_endpoints` | Number of distinct endpoint paths called in the period           |

<Tip>
  Calculate your error rate as `error_calls / total_calls`. If this ratio rises above your baseline, check the raw logs to identify which endpoint is failing and what status codes are returned.
</Tip>

## Raw request logs

`GET /api/v1/console/logs` returns paginated individual request records for a key. Use this to debug a specific failure, audit what your application called, or investigate an unexpected `401`.

**Query parameters:**

| Parameter    | Required | Default | Notes                       |
| ------------ | -------- | ------- | --------------------------- |
| `api_key_id` | Yes      | —       | UUID of the API key         |
| `limit`      | No       | `50`    | Items per page. Maximum 200 |
| `offset`     | No       | `0`     | Number of items to skip     |

```bash theme={null}
curl "https://api.predexy.com/api/v1/console/logs?\
api_key_id=3fa85f64-5717-4562-b3fc-2c963f66afa6\
&limit=20\
&offset=0" \
  -H "Authorization: Bearer <your-access-token>"
```

**Response:**

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

**Response fields (`UsageLogEntry`):**

| Field              | Description                                                       |
| ------------------ | ----------------------------------------------------------------- |
| `endpoint`         | API path called (e.g. `/api/v1/external/arbitrage/opportunities`) |
| `method`           | HTTP method (`GET`, `POST`, etc.)                                 |
| `status_code`      | HTTP status code returned by the server                           |
| `response_time_ms` | Server-side response time in milliseconds                         |
| `created_at`       | Timestamp of the request (ISO 8601)                               |

To page through results, increment `offset` by your `limit` value on each request until `offset >= meta.total`.

## How to find your API key UUID

The `api_key_id` parameter is the UUID assigned to your key at creation — not the key itself. To retrieve it, call the list keys endpoint:

```bash theme={null}
curl https://api.predexy.com/api/v1/console/keys \
  -H "Authorization: Bearer <your-access-token>"
```

The `id` field in each object is the UUID you pass to the stats and logs endpoints.

## Practical tips

**Track your error rate over time.** Use the daily stats with `limit=30` to build a 30-day view of `error_calls / total_calls`. A sudden increase often signals a breaking change in your integration or a rate limit being hit (`429` in the raw logs).

**Identify slow endpoints.** The `unique_endpoints` field in stats tells you how many different paths were called in a period. When `p95_latency_ms` spikes, drill into raw logs filtered around that time window to see which endpoint is responsible.

**Monitor quota usage.** Compare `total_calls` against your key's `rate_limit` (visible from the [list keys](/console/api-keys#listing-your-keys) response, in requests per minute). If you are regularly hitting your limit — indicated by `429` status codes in the logs — consider requesting a higher rate limit when creating a new key.

**Use hourly granularity for active debugging.** When investigating an incident from the past few hours, switch to `granularity=hourly` and `limit=24` to see per-hour breakdowns instead of daily aggregates.