# Usage

## Get user usage

Retrieve usage metrics for a specific user, including quotas and remaining allowances for the current billing period.

**Endpoint:** `GET /v3/users/{user_id}/usage`

**Path parameters:**

| <p><br>Parameter</p> | Type   | Description      |
| -------------------- | ------ | ---------------- |
| `user_id`            | string | UUID of the user |

**Example response:**

```json
{
  "period": {
    "start": "2025-06-01T00:00:00.000Z",
    "end": "2025-06-30T23:59:59.000Z",
    "days_remaining": 15
  },
  "quota": {
    "messages": 1000,
    "voice_seconds": 3600.0,
    "video_seconds": 1800.0
  },
  "usage": {
    "messages": 250,
    "voice_seconds": 900.0,
    "video_seconds": 120.0
  },
  "remaining": {
    "messages": 750,
    "voice_seconds": 2700.0,
    "video_seconds": 1680.0
  }
}
```

**Response fields:**

| Field                     | Type    | Description                     |
| ------------------------- | ------- | ------------------------------- |
| `period.start`            | string  | Billing period start (ISO 8601) |
| `period.end`              | string  | Billing period end (ISO 8601)   |
| `period.days_remaining`   | integer | Days left in current period     |
| `quota.messages`          | integer | Total message allowance         |
| `quota.voice_seconds`     | number  | Total voice seconds allowance   |
| `quota.video_seconds`     | number  | Total video seconds allowance   |
| `usage.messages`          | integer | Messages used this period       |
| `usage.voice_seconds`     | number  | Voice seconds used              |
| `usage.video_seconds`     | number  | Video seconds used              |
| `remaining.messages`      | integer | Messages remaining              |
| `remaining.voice_seconds` | number  | Voice seconds remaining         |
| `remaining.video_seconds` | number  | Video seconds remaining         |

***

## Get user tier

Retrieve the current access tier for a specific user.

**Endpoint:** `GET /v3/users/{user_id}/tier`

**Path parameters:**

| Parameter | Type   | Description      |
| --------- | ------ | ---------------- |
| `user_id` | string | UUID of the user |

**Example request:**

```bash
curl "https://api.delphi.ai/v3/users/u-123/tier" \
  -H "x-api-key: YOUR_API_KEY"
```

**Example response:**

```json
{
  "tier": "GROWTH"
}
```

{% hint style="info" %}
The default tier is `"JUST ME"` if no custom tier has been assigned.
{% endhint %}