List Screenshots

This feature is currently in beta. Contact [email protected] if you're interested in trying the beta.

List approved screenshots

get

Returns a paginated list of approved screenshots for the organization within the specified time range.

Authorizations

Bearer

AuthorizationstringRequired

API key necessary to authenticate API requests

Path parameters

organization_slugstringRequired

Organization slug

Example: abc-company

Query parameters

fromstring · date-timeOptional

Start of approval time range (ISO 8601 datetime, defaults to 24 hours ago)

Example: 2024-01-01T00:00:00Z

tostring · date-timeOptional

End of approval time range (ISO 8601 datetime)

Example: 2024-12-31T23:59:59Z

orderstring · enumOptional

Sort order by approved_at (default: asc)

Default: ascPossible values:

pageintegerOptional

Page number for pagination

Example: 1

per_pageinteger · max: 500Optional

Number of results per page (max 500)

Example: 100

includestring · enumOptional

Additional data to include. ad.creative enables platform creative objects (xandr_creative, google_dv360_creative, google_ad_manager_creative, trade_desk_creative) and preview_image_url on each ad. Without it, those properties are omitted entirely.

Example: ad.creativePossible values:

Header parameters

AuthorizationstringOptional

Bearer token for API authentication

Responses

200

OK

application/json

401

Unauthorized

403

Forbidden

422

Unprocessable Entity

application/json

get

/api/v1/orgs/{organization_slug}/screenshots

HTTPcURLJavaScriptPython

GET /api/v1/orgs/{organization_slug}/screenshots HTTP/1.1
Host: app.adreform.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "screenshots": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "uploaded",
      "image_url": "https://example.com",
      "device": "text",
      "site": {
        "url": "https://example.com",
        "host": "text"
      },
      "ad": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "lookup_key": "text",
        "external_id": "text",
        "preview_image_url": "https://example.com",
        "width": 1,
        "height": 1,
        "media": {
          "type": "html_tag"
        },
        "xandr_creative": {},
        "google_dv360_creative": {},
        "google_ad_manager_creative": {},
        "trade_desk_creative": {}
      },
      "screenshot_set": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "created_at": "2026-03-11T13:38:37.974Z",
        "approved_at": "2026-03-11T13:38:37.974Z",
        "status": "approved",
        "campaign": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text"
        }
      }
    }
  ]
}

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

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

# 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)

{
  "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

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

Google DV360

"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

"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

"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:

{
  "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.

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