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

# Get Credit Usage

> Get credit usage breakdown by tile and date.

Returns aggregated credit usage over a date range.

The response includes:

* totals across the range
* grouped usage by tile
* grouped usage by date
* grouped usage by both date and tile

Tile names (for example `YouTube Download`, `Rough Cut`, `Clips`) are resolved from node metadata associated with each credit log.

## Query Parameters

| Parameter    | Type   | Required | Description                                                           |
| ------------ | ------ | -------- | --------------------------------------------------------------------- |
| `start_date` | string | No       | ISO date/datetime start bound. Defaults to 30 days before `end_date`. |
| `end_date`   | string | No       | ISO date/datetime end bound. Defaults to now.                         |
| `limit`      | number | No       | Max raw usage events scanned (1 - 10,000). Default: `5,000`.          |

## Request

```bash theme={null}
curl -X GET "https://api.mosaic.so/credits/usage?start_date=2026-03-01T00:00:00.000Z&end_date=2026-03-31T23:59:59.999Z&limit=5000" \
  -H "Authorization: Bearer mk_your_api_key"
```

## Response

```json theme={null}
{
  "organization_id": "d808af70-fc57-4f90-95ca-186a9cbf2ef7",
  "date_range": {
    "start_date": "2026-03-01T00:00:00.000Z",
    "end_date": "2026-03-31T23:59:59.999Z"
  },
  "summary": {
    "total_credits_used": 14220,
    "total_events": 298,
    "matching_events": 298,
    "returned_events": 298,
    "truncated": false
  },
  "breakdown": {
    "by_tile": [
      {
        "tile_id": "a4c6ee9a-4ff2-43f8-9a9a-d4ad6dd20f3a",
        "tile_name": "Rough Cut",
        "credits_used": 7210,
        "events": 142
      },
      {
        "tile_id": "3cfd7bcb-f4cb-4bd3-8f81-a3de9af16f14",
        "tile_name": "Clips",
        "credits_used": 5030,
        "events": 101
      }
    ],
    "by_date": [
      {
        "date": "2026-03-01",
        "credits_used": 420,
        "events": 11
      },
      {
        "date": "2026-03-02",
        "credits_used": 388,
        "events": 9
      }
    ],
    "by_date_and_tile": [
      {
        "date": "2026-03-01",
        "tile_id": "a4c6ee9a-4ff2-43f8-9a9a-d4ad6dd20f3a",
        "tile_name": "Rough Cut",
        "credits_used": 420,
        "events": 11
      }
    ]
  }
}
```

## Response Fields

| Field                                       | Type           | Description                                         |
| ------------------------------------------- | -------------- | --------------------------------------------------- |
| `organization_id`                           | string         | Organization identifier.                            |
| `date_range.start_date`                     | string         | Start of the queried range (ISO).                   |
| `date_range.end_date`                       | string         | End of the queried range (ISO).                     |
| `summary.total_credits_used`                | number         | Total credits consumed in the returned range.       |
| `summary.total_events`                      | number         | Number of charge events included in aggregation.    |
| `summary.matching_events`                   | number         | Total matching events before `limit` truncation.    |
| `summary.returned_events`                   | number         | Number of events processed in this response window. |
| `summary.truncated`                         | boolean        | `true` when `matching_events > returned_events`.    |
| `breakdown.by_tile[].tile_id`               | string         | Tile/node type identifier.                          |
| `breakdown.by_tile[].tile_name`             | string \| null | Human-readable tile name.                           |
| `breakdown.by_tile[].credits_used`          | number         | Credits used by this tile.                          |
| `breakdown.by_tile[].events`                | number         | Number of usage events for this tile.               |
| `breakdown.by_date[].date`                  | string         | UTC date (`YYYY-MM-DD`).                            |
| `breakdown.by_date[].credits_used`          | number         | Credits used on this date.                          |
| `breakdown.by_date[].events`                | number         | Number of usage events on this date.                |
| `breakdown.by_date_and_tile[].date`         | string         | UTC date (`YYYY-MM-DD`).                            |
| `breakdown.by_date_and_tile[].tile_id`      | string         | Tile/node type identifier.                          |
| `breakdown.by_date_and_tile[].tile_name`    | string \| null | Human-readable tile name.                           |
| `breakdown.by_date_and_tile[].credits_used` | number         | Credits used by this tile on this date.             |
| `breakdown.by_date_and_tile[].events`       | number         | Number of usage events for this tile on this date.  |