# Quota API

Base path: `/api/v1/quota`

All endpoints require `Authorization: Bearer <jwt>`.

Related: [[02 - Videos API]], [[01 - System Overview]]

---

## GET /quota/history

Get YouTube API quota usage history for the current team.

**Query parameters:**

| Param | Type | Description |
|---|---|---|
| `from` | ISO date | Start of the date range |
| `to` | ISO date | End of the date range |
| `channelId` | string | Filter by channel |

**Response:**

```json
[
  {
    "id": "cuid",
    "datePt": "ISO datetime",
    "units": 50,
    "operation": "videos.update",
    "actionId": "uuid",
    "actionType": "video_sync",
    "channelId": "cuid",
    "videoId": "cuid",
    "video": {
      "id": "cuid",
      "title": "Video Title",
      "youtubeVideoId": "abc123"
    }
  }
]
```

**Field notes:**

| Field | Notes |
|---|---|
| `datePt` | Timestamp of the quota spend, in Pacific Time (quota resets at midnight PT). |
| `units` | Number of quota units consumed by the operation. |
| `operation` | YouTube API method called (e.g. `videos.update`). |
| `actionType` | Internal action that triggered the spend (e.g. `video_sync`). |

---

## GET /quota/today

Get the total YouTube API quota consumed today (Pacific Time), plus the daily limit and remaining units.

**Response:**

```json
{
  "used": 450,
  "limit": 10000,
  "remaining": 9550
}
```

---

## Notes

- The YouTube API quota limit is **10,000 units per day**, resetting at midnight Pacific Time.
- A `videos.update` call (triggered by a sync job) costs **50 units**.
- `QuotaService.canSpend()` and `.spend()` are called before every YouTube write. If the remaining quota is insufficient, the operation is rejected.
- Quota is tracked per team and per channel.
- See [[02 - Videos API]] — `POST /videos/:id/sync` for the sync flow that consumes quota.