---
title: "Credits"
description: "List and manage your TurboPentest credits through the API, including filtering by status to see available, consumed, and expired pentest credits."
canonical: https://turbopentest.com/docs/api/credits
source: "TurboPentest Docs"
---

# Credits

## List credits

```
GET /api/v2/credits
```

Returns all credits for your account. Use the optional `status` query parameter to filter by credit status.

**Query parameters**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | string | No | Filter by status: `available`, `used`, `expired`, or `scheduled` |

**Response** `200 OK`

```json
[
  {
    "id": "cred_001",
    "sourceType": "subscription",
    "status": "available",
    "createdAt": "2026-01-01T00:00:00Z",
    "usedAt": null,
    "expiresAt": "2027-01-01T00:00:00Z"
  },
  {
    "id": "cred_002",
    "sourceType": "one_time",
    "status": "used",
    "createdAt": "2026-01-15T10:30:00Z",
    "usedAt": "2026-02-01T14:00:00Z",
    "expiresAt": "2027-01-15T10:30:00Z"
  }
]
```

## Get credit balance

```
GET /api/credits/balance
```

Returns aggregated credit counts for your account. This is the fastest way to check how many credits you have available.

**Response** `200 OK`

```json
{
  "available": 8,
  "used": 4,
  "expired": 0,
  "scheduled": 0,
  "expiringSoon": 2,
  "total": 12,
  "byTier": { "recon": 0, "standard": 8, "deep": 0, "blitz": 0 },
  "tiersByStatus": { "available": { "recon": 0, "standard": 8, "deep": 0, "blitz": 0 }, "...": {} }
}
```

| Field | Description |
|-------|-------------|
| `available` | Credits ready to use |
| `used` | Credits consumed by pentests |
| `expired` | Credits that passed their 1-year expiry date |
| `scheduled` | Credits reserved for scheduled pentests |
| `expiringSoon` | Available credits expiring within 30 days |
| `total` | Sum of available, used, expired, and scheduled |
| `byTier` | Available credits broken down by tier |
| `tiersByStatus` | Tier breakdown for each status |

## Consume a credit

```
POST /api/v2/credits/{id}/use
```

Consume a specific credit to start a pentest against a target. The target's domain must be verified.

**Request body**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `targetId` | string | Yes | The ID of the target to pentest |

**Response** `200 OK`

```json
{
  "scanId": "9b2e6f4a-1c3d-4e5f-8a7b-6c5d4e3f2a10"
}
```

**Error responses**

| Status | Condition |
|--------|-----------|
| `400` | Credit is not in `available` status |
| `400` | Domain verification has expired |
| `400` | Missing `targetId` in request body |
| `404` | Credit not found |
| `404` | Target not found |

Each pentest consumes one credit. Credits are consumed using FIFO order (oldest first) when no specific credit ID is provided. All credits expire 1 year from the date of purchase.