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

# List transactions

> List user credit transactions.

## Base URL

* **Production:** `https://api.boltroute.ai`
* **Staging:** `https://staging-api.example.com`
* **Local:** `http://localhost:8080`

## Conventions

* **Content-Type:** `application/json`
* **Date/Time:** ISO 8601 (UTC)
* **Pagination:** `limit`, `offset`
* **Error format:** JSON error payload with `code`, `message`, and optional `details`

Example error payload:

```json theme={null}
{
  "error": {
    "code": "STRING_CODE",
    "message": "Human readable message",
    "details": [
      { "field": "fieldA", "reason": "required" }
    ]
  }
}
```

***

# Endpoints

## GET /api/v1/credits/transactions

**Summary:** List credit transactions for the authenticated user.

**Idempotent:** Yes
**Tags:** credits

### Request

**Headers**

* `Content-Type: application/json`

**Query Params**

| Name   | Type    | Required | Default | Description                              | Example |
| ------ | ------- | -------- | ------- | ---------------------------------------- | ------- |
| limit  | integer | No       | 50      | Number of transactions to return (1-100) | `50`    |
| offset | integer | No       | 0       | Number of transactions to skip           | `0`     |

### Responses

**200 OK - List of credit transactions**

```json theme={null}
{
  "transactions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "grant",
      "amount": 100,
      "balance_after": 500,
      "reason": "Manual adjustment",
      "metadata": {
        "source": "api_key",
        "api_key_id": "550e8400-e29b-41d4-a716-446655440000",
        "api_key_purpose": "zapier"
      },
      "created_at": "2023-01-01T12:00:00Z"
    }
  ],
  "total": 120,
  "limit": 50,
  "offset": 0
}
```

**Response Fields**

| Field                                      | Type    | Description                                                                  |
| ------------------------------------------ | ------- | ---------------------------------------------------------------------------- |
| transactions                               | array   | Credit transactions                                                          |
| transactions\[].id                         | string  | Transaction UUID                                                             |
| transactions\[].user\_id                   | string  | User UUID                                                                    |
| transactions\[].type                       | string  | `grant` or `deduction`                                                       |
| transactions\[].amount                     | integer | Credit delta                                                                 |
| transactions\[].balance\_after             | integer | Balance after the transaction                                                |
| transactions\[].reason                     | string  | Optional reason                                                              |
| transactions\[].metadata                   | object  | Optional metadata                                                            |
| transactions\[].metadata.source            | string  | Credit source attribution (`api_key`, `frontend`, or missing on legacy rows) |
| transactions\[].metadata.api\_key\_id      | string  | API key UUID when the request was attributed to an API key                   |
| transactions\[].metadata.api\_key\_purpose | string  | API key purpose when available (for example `zapier`)                        |
| transactions\[].created\_at                | string  | ISO 8601 timestamp                                                           |
| total                                      | integer | Total number of transactions                                                 |
| limit                                      | integer | Page size                                                                    |
| offset                                     | integer | Offset into the result set                                                   |

**400 Bad Request - Invalid query parameters**

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "limit must be less than or equal to 100"
  }
}
```

**401 Unauthorized**

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid token"
  }
}
```

**404 Not Found**

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "User not found"
  }
}
```

**500 Internal Server Error**

```json theme={null}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Unexpected server error"
  }
}
```

### Examples

**cURL**

```bash theme={null}
curl -X GET \
  'https://api.boltroute.ai/api/v1/credits/transactions?limit=50&offset=0'
```