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

# List screenshots

> GET /v1/screenshots — retrieve a paginated list of your screenshots.

## Endpoint

```
GET https://api.screenshotly.dev/v1/screenshots
```

## Headers

| Header      | Required | Description  |
| ----------- | -------- | ------------ |
| `X-API-Key` | Yes      | Your API key |

## Query parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="limit" type="integer" default="10">
  Number of screenshots per page.
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `pending`, `processing`, `completed`, or `failed`.
</ParamField>

<ParamField query="format" type="string">
  Filter by format: `png`, `jpeg`, `webp`, or `pdf`.
</ParamField>

<ParamField query="search" type="string">
  Search screenshots by URL (case-insensitive partial match).
</ParamField>

<ParamField query="startDate" type="string">
  Filter screenshots created on or after this date (ISO 8601 format).
</ParamField>

<ParamField query="endDate" type="string">
  Filter screenshots created on or before this date (ISO 8601 format).
</ParamField>

## Response

### 200 OK

```json theme={null}
{
  "success": true,
  "data": [
    {
      "_id": "67b8a1c2d3e4f5a6b7c8d9e0",
      "url": "https://example.com",
      "name": "Homepage",
      "status": "completed",
      "imageUrl": "https://cdn.screenshotly.dev/screenshots/67b8a1c2d3e4f5a6b7c8d9e0.png",
      "metadata": {
        "fileSize": 245760,
        "format": "png",
        "dimensions": { "width": 1280, "height": 1024 }
      },
      "createdAt": "2025-05-14T10:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "limit": 10,
    "pages": 5
  }
}
```

## Examples

### List all completed screenshots

```bash theme={null}
curl "https://api.screenshotly.dev/v1/screenshots?status=completed&limit=20" \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY"
```

### Search by URL

```bash theme={null}
curl "https://api.screenshotly.dev/v1/screenshots?search=example.com" \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY"
```

### Filter by date range

```bash theme={null}
curl "https://api.screenshotly.dev/v1/screenshots?startDate=2025-05-01&endDate=2025-05-31" \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY"
```