# Get API key usage

Read a cursor-paginated forensic log of requests made with a key — useful for audits.

Returns a cursor-paginated log of requests made with a key, newest first. Use it to answer "what did this key touch?" during an audit or incident.

## Path parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | string | The API key ID. |

## Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | Rows per page. Default `100`, range 1–500. |
| `before` | string | No | ISO 8601 cursor — return rows older than this timestamp. |

## Example request

```bash
curl "https://app.talent-ray.com/api/admin/api-keys/apikey_xyz789/usage?limit=50" \
  -H "Authorization: Bearer tr_YOUR_ADMIN_KEY"
```

## Response

`200 OK`

```json
{
  "success": true,
  "data": {
    "key": {
      "id": "apikey_xyz789",
      "name": "Karaca SAP nightly sync",
      "createdAt": "2026-06-04T10:00:00Z",
      "lastRequest": "2026-06-04T15:30:45Z",
      "requestCount": 1250,
      "owner": { "id": "user_abc123", "email": "admin@company.com", "name": "Admin User" }
    },
    "rows": [
      {
        "id": "usage_001",
        "timestamp": "2026-06-04T15:30:45Z",
        "method": "POST",
        "path": "/api/admin/api-keys",
        "ip": "192.0.2.100",
        "userAgent": "curl/7.68.0",
        "authEndpoint": "/get-session"
      }
    ],
    "pagination": { "limit": 50, "hasMore": true, "nextBefore": "2026-06-04T15:20:00Z" }
  }
}
```

To fetch the next page, pass `pagination.nextBefore` as the `before` query parameter. When `hasMore` is `false`, there are no more rows.

## Status codes

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `401` | No valid API key. |
| `403` | Caller is not an admin. |
| `404` | Key not found. |
| `429` | Rate limited. |