---
title: "Request a project PDF report for a window and filters"
method: POST
path: "/projects/{project_id}/reports"
tags: ["Reports"]
---

# Request a project PDF report for a window and filters

`POST /projects/{project_id}/reports`

## Request

- Base URL: `https://adslighthouse.com/api/v1`
- URL: `https://adslighthouse.com/api/v1/projects/{project_id}/reports`
- Auth: HTTP bearer

Requests a PDF report of a project's saved observations: executive summary with period-over-period change, coverage and methodology, trends, top advertisers with presence and share, new and returning advertisers, brand mentions, affiliate findings, advertiser deep dives, ad copy, Shopping when enabled, and keyword and evidence appendices. Choose comparable windows with the same filters and time zone for a period comparison. It is generated in the background: poll get_report_status, then use get_report_download_link. Idempotent by selection: while a report for the same project, window, time zone, filters and branding is queued, running or ready, the same report is returned (created is false). With branding agency the PDF carries the account's report branding instead of ours; a branding change after a request makes the next request a new file. Each account can create 20 new reports per UTC day. The report states that observations are not proof of spend or infringement; repeat that when you share it. Defaults to the last 30 days.

## Path parameters

- `project_id` string, required: The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.

## Request body

- object
  - `range` '7d' | '14d' | '30d' | '12m' | 'custom': Window ending today: 7d, 14d, 30d (default) or 12m. Use custom with from and to for fixed dates.
  - `from` string: First local day, YYYY-MM-DD (custom range).
  - `to` string: Last local day, YYYY-MM-DD, included in full (custom range).
  - `time_zone` string: IANA time zone for day boundaries, such as America/New_York. Defaults to the time zone of the person the credential acts for.
  - `engine` union: Search engine, or a list of engines combined with OR.
    - 'google' | 'bing'
    - string[]
  - `device` union: Device, or a list combined with OR.
    - 'desktop' | 'mobile'
    - string[]
  - `os` union: Operating system. unspecified matches checks that did not pin one. Must fit the chosen device.
    - 'windows' | 'macos' | 'android' | 'ios' | 'unspecified'
    - string[]
  - `country` union: ISO 3166-1 alpha-2 country code such as US, or a list.
    - string
    - string[]
  - `location` union: Saved location key: code:<location code>, name:<label> or country:<ISO code>. get_project_details lists the keys that have data.
    - string
    - string[]
  - `branding` 'default' | 'agency': default: our branding. agency: the account's report branding (get_report_branding) on the cover, headers, footers and file properties, with no mention of our name; needs a plan with white-label reports and branding set up.
  - `prepared_for` string: With branding agency: the client name on the cover, up to 120 characters. Defaults to the project name. Part of the idempotency: another name makes another file.

## Response `202`

Request a project PDF report for a window and filters

- object
  - `created` boolean, required: False when an existing report for this selection was returned.
  - `report` object, required
    - `id` string, required
    - `project_id` string, required
    - `status` 'queued' | 'running' | 'ready' | 'failed' | 'expired', required: queued and running: still generating. ready: download it. failed: see error. expired: the file was deleted; request it again.
    - `error` object, nullable, required
      - `code` 'too_large' | 'unavailable' | 'generation_failed', required
      - `message` string, required
    - `window` object, nullable, required: The local calendar days the report covers, in its time zone.
      - `from` string, required
      - `to` string, required
      - `time_zone` string, required
    - `filters` object, required: Applied filters by dimension; empty when every observation is included.
      - `engine` string[]
      - `device` string[]
      - `os` string[]
      - `country` string[]
      - `location` string[]
    - `requested_at` string, required
    - `completed_at` string, nullable, required
    - `expires_at` string, required: When a ready report's file is deleted, 7 days after it was generated.
    - `page_count` integer, nullable, required
    - `size_bytes` integer, nullable, required
    - `branding` object, required: The branding the file was requested with.
      - `kind` 'default' | 'agency', required
      - `agency_name` string, nullable, required
      - `prepared_for` string, nullable, required
  - `request_id` string

## Other responses

- `400`: Invalid parameters, cursor or body.
- `401`: Missing, invalid, expired or revoked credential.
- `403`: The credential lacks the write scope, the plan does not include the API, or the allowance is used up.
- `404`: Unknown project, keyword or run in this account.
- `409`: The idempotency key was already used for a different request.
- `429`: Rate limit reached. Retry after the Retry-After seconds.
- `503`: The requested service or file is temporarily unavailable.

---

[API](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api.md) · [All operations](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api/revisions/e1a4a40b11a9?raw)