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

# Get Test History

> Run reports of a test over a date range

> [!NOTE]
>
> **Smart Delivery v2 (Deliverability Test) API**: the deliverability (inbox placement) test that sends your campaign email to seed inboxes and reports where it landed. Contact [support@smartlead.ai](mailto:support@smartlead.ai) for access.

## Overview

One item per completed run, oldest first. Without `from` and `to` it covers the last 30 days (UTC); the range is at most 400 days. A page holds the newest runs (up to 100), listed oldest first; use `nextCursor` to get the runs before them.

## Path Parameters

**id** `string` *required*

Test ID (UUID)

## Query Parameters

**api\_key** `string` *required*

Your SmartLead API key

**from** `string`

First day, `YYYY-MM-DD` (UTC)

**to** `string`

Last day, `YYYY-MM-DD` (UTC)

**limit** `number`

Page size, 1 to 100. Default 100

**cursor** `string`

`nextCursor` from the previous page

```bash cURL theme={null}
curl -X GET "https://sl-sd-api.smartlead.ai/api/v1/smart-delivery/tests/3f2b8c1e-5d4a-4e7b-9a60-1c2d3e4f5a6b/history?api_key=YOUR_KEY"
```

```python Python theme={null}
import requests

API_KEY = "YOUR_API_KEY"

response = requests.get(
    "https://sl-sd-api.smartlead.ai/api/v1/smart-delivery/tests/3f2b8c1e-5d4a-4e7b-9a60-1c2d3e4f5a6b/history",
    params={"api_key": API_KEY}
)
print(response.status_code)
print(response.json())
```

```javascript JavaScript theme={null}
const API_KEY = 'YOUR_API_KEY';

const response = await fetch(
  `https://sl-sd-api.smartlead.ai/api/v1/smart-delivery/tests/3f2b8c1e-5d4a-4e7b-9a60-1c2d3e4f5a6b/history?api_key=${API_KEY}`,
  {
    method: 'GET'
  }
);
console.log(await response.json());
```

## Response Fields

**from** `string`

First day of the range

**to** `string`

Last day of the range

**items** `array`

**run**

**runId** `string`

Run ID

**runNo** `number`

Run number

**completedAt** `string`

Completion time

**score** `number | null`

Score

**band** `string | null`

`poor`, `fair` or `good`

**counts** `object`

Counts for the emails sent: `expected`, `sent`, `failed`, `inbox`, `tab`, `spam`, `missing`, `unreadable`, `notSent`, `unconfirmed`, `bouncedSeed`, `bouncedSender`, `bouncedUnknown`, `spfFail`, `dkimFail`, `dmarcFail`, and `inboxRate` (inbox share of the emails that reached a verdict, 0 to 1, or `null` when none did). Seed-side bounces (`bouncedSeed`) are left out of the placement rate; sender-side and unknown bounces count as not delivered.

**nextCursor** `string | null`

Pass as `cursor` to get the runs before this page. `null` when there are no more

## Response Codes

**200** `Success`

Success

**400** `Error`

Invalid date range (`RANGE_INVALID`)

**404** `Error`

Test not found (`TEST_NOT_FOUND`)

**401** `Unauthorized`

Missing, invalid or expired API key (`UNAUTHORIZED`)

**403** `Forbidden`

Client (agency) API keys are not allowed (`CLIENT_NOT_ALLOWED`), or your plan does not include API access (`API_ACCESS_RESTRICTED`)

**429** `Too Many Requests`

Too many requests for this API key. Wait the number of seconds in the `Retry-After` header (`RATE_LIMITED`)

```json 200 - Success theme={null}
{
  "from": "2026-10-19",
  "to": "2026-11-17",
  "items": [
    { "runId": "b7d2e6f1-4a38-4c19-9e05-6f8a1b2c3d4e", "runNo": 1, "completedAt": "2026-11-10T09:21:00.000Z", "score": 66, "band": "fair", "counts": { "sent": 24, "inbox": 15, "spam": 6, "inboxRate": 0.625 } },
    { "runId": "8a1c7e90-2b3d-4c5e-8f60-7a9b0c1d2e3f", "runNo": 2, "completedAt": "2026-11-17T09:21:00.000Z", "score": 72, "band": "fair", "counts": { "sent": 24, "inbox": 18, "spam": 3, "inboxRate": 0.75 } }
  ],
  "nextCursor": null
}
(counts abbreviated)
```

```json Error - Unauthorized theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API Key"
  }
}
```

## Related Endpoints

* [Get Run Report](https://api.smartlead.ai/api-reference/smart-delivery-v2/run-report.md)
* [Compare Two Runs](https://api.smartlead.ai/api-reference/smart-delivery-v2/compare-runs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.