# List Screenshots

{% hint style="info" %}
This feature is currently in beta. Contact <support@adreform.com> if you're interested in trying the beta.
{% endhint %}

{% openapi src="<https://2718083151-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWXKnh5nreVaQejzmqBUM%2Fuploads%2Fgit-blob-62087cc88de5585e2f431015233e37e65369350e%2Fad-reform-swagger.yaml?alt=media>" path="/api/v1/orgs/{organization\_slug}/screenshots" method="get" %}
[ad-reform-swagger.yaml](https://2718083151-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWXKnh5nreVaQejzmqBUM%2Fuploads%2Fgit-blob-62087cc88de5585e2f431015233e37e65369350e%2Fad-reform-swagger.yaml?alt=media)
{% endopenapi %}

## Overview

This endpoint returns approved screenshots with their associated ad data, site information, and screenshot set details. Use it to poll for newly approved screenshots within a time range.

## Query Parameters

| Parameter  | Required | Description                                                                                                                           |
| ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `from`     | No       | Start of approval time range (ISO 8601 datetime). Defaults to 24 hours ago.                                                           |
| `to`       | No       | End of approval time range (ISO 8601 datetime). Defaults to current time.                                                             |
| `order`    | No       | Sort order by `approved_at`. Either `asc` (default) or `desc`.                                                                        |
| `page`     | No       | Page number for pagination                                                                                                            |
| `per_page` | No       | Number of results per page (default: 100, max: 500)                                                                                   |
| `include`  | No       | Comma-separated list of additional data to include. Supported: `ad.creative` (includes platform creative data and preview image URL). |

## Pagination

Results are paginated using `Link` response headers.

### Response Headers

| Header | Description                                         |
| ------ | --------------------------------------------------- |
| `Link` | Standard pagination links (`first`, `prev`, `next`) |

### Example

```http
Link: <https://app.adreform.com/api/v1/orgs/abc-company/screenshots?from=2026-01-01T00:00:00Z&page=2&per_page=100>; rel="next"
```

## Polling Pattern

Use this endpoint to poll for newly approved screenshots:

1. Store a `last_polled_at` timestamp
2. On each poll, set `from` to your `last_polled_at` value
3. Process all pages of results
4. Update `last_polled_at` to the current time

```bash
# Initial poll - get all screenshots approved in the last 24 hours
curl "https://app.adreform.com/api/v1/orgs/your-org/screenshots" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Subsequent poll - get screenshots approved since last poll
curl "https://app.adreform.com/api/v1/orgs/your-org/screenshots?from=2026-03-01T12:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Response

### Success Response (200 OK)

```json
{
  "screenshots": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "uploaded",
      "image_url": "https://app.adreform.com/attachments/perm/...",
      "device": "desktop",
      "site": {
        "url": "https://example.com",
        "host": "example.com"
      },
      "ad": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Banner 300x250",
        "lookup_key": "banner-300x250-v1",
        "external_id": null,
        "width": 300,
        "height": 250,
        "media": {
          "type": "html_tag"
        }
      },
      "screenshot_set": {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "created_at": "2026-03-01T10:00:00Z",
        "approved_at": "2026-03-01T14:30:00Z",
        "status": "approved",
        "campaign": {
          "id": "d4e5f6a7-b8c9-0123-def1-234567890123",
          "name": "Q1 2026 Campaign"
        }
      }
    }
  ]
}
```

### Platform Creative Data

Platform creative fields (`xandr_creative`, `google_dv360_creative`, `google_ad_manager_creative`, `trade_desk_creative`) and `preview_image_url` are only included when `?include=ad.creative` is passed. When included, the corresponding fields are populated if the ad is linked to a platform creative:

#### Xandr

```json
"xandr_creative": {
  "xandr_id": 123456,
  "name": "My Xandr Creative",
  "line_item": {
    "xandr_id": 789012,
    "name": "My Line Item",
    "state": "active"
  }
}
```

#### Google DV360

```json
"google_dv360_creative": {
  "google_dv360_id": "123456",
  "display_name": "My DV360 Creative",
  "line_item": {
    "google_dv360_id": "789012",
    "display_name": "My Line Item",
    "entity_status": "ENTITY_STATUS_ACTIVE"
  }
}
```

#### Google Ad Manager

```json
"google_ad_manager_creative": {
  "google_ad_manager_id": "123456",
  "name": "My GAM Creative",
  "line_item": {
    "google_ad_manager_id": "789012",
    "name": "My Line Item",
    "status": "DELIVERING"
  }
}
```

#### The Trade Desk

```json
"trade_desk_creative": {
  "trade_desk_id": "abc123",
  "name": "My TTD Creative",
  "ad_group": {
    "trade_desk_id": "def456",
    "name": "My Ad Group"
  }
}
```

## Disabled Organizations

When an organization is disabled (i.e. it does not have an active subscription), the API will return a 403 Forbidden response:

```json
{
  "status": "failure",
  "errors": {
    "organization": ["Your organization is disabled. Upgrade to keep using the API: https://adreform.com/o/_/billing"]
  }
}
```

## Error Responses

### 401 Unauthorized

Returned when the API key is missing or invalid.

### 403 Forbidden

Returned when the organization is disabled or the `api_screenshot_polling` feature is not enabled.

### 422 Unprocessable Entity

Returned when query parameters are invalid.

```json
{
  "status": "failure",
  "errors": {
    "from": ["is not a valid ISO 8601 datetime"]
  }
}
```