generate_report
Trigger generation of a report. Generation is asynchronous — poll with get_report until status is "ready" or "failed".
The created report is tagged created_via="ai" to distinguish it from UI-initiated ("human") and scheduled ("scheduled") reports.
Parameters#
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
template_key | string | yes | Template key from list_report_templates | |
ad_account_ids | string[] | yes | 1–10 ad account ids; must belong to your org | |
period_start | string | yes | YYYY-MM-DD, inclusive | |
period_end | string | yes | YYYY-MM-DD, inclusive; ≥ period_start, ≤ 31 days span | |
title | string? | no | auto | Defaults to "{template name} ({period_start} – {period_end})"; max 200 chars |
sections | string[]? | no | null | Override the template’s default section list; must be a subset of registry keys |
template_version | integer? | no | latest | Pin to a specific template version; defaults to the active version |
Returns#
json
{
"report_id": "ad_rpt_abc",
"status": "pending",
"title": "Weekly Check-In (2026-04-15 – 2026-04-21)",
"template": { "key": "weekly_check_in", "version": 1, "name": "Weekly Check-In" },
"period_start": "2026-04-15",
"period_end": "2026-04-21",
"ad_account_ids": ["ad_acct_abc"],
"poll_with": "get_report(report_id)",
"source": "adlyse.reports@v1"
}Errors#
error_type | When |
|---|---|
auth_error | Missing / invalid API key |
not_found | Template key unknown; or any ad_account_id not in your org |
validation_error | Empty ad_account_ids, bad date format, period_end < period_start, period > 31 days |
Example#
Request:
json
{
"template_key": "weekly_check_in",
"ad_account_ids": ["ad_acct_abc"],
"period_start": "2026-04-15",
"period_end": "2026-04-21"
}Response:
json
{
"report_id": "ad_rpt_xyz",
"status": "pending",
"title": "Weekly Check-In (2026-04-15 – 2026-04-21)",
"template": { "key": "weekly_check_in", "version": 1, "name": "Weekly Check-In" },
"period_start": "2026-04-15",
"period_end": "2026-04-21",
"ad_account_ids": ["ad_acct_abc"],
"poll_with": "get_report(report_id)",
"source": "adlyse.reports@v1"
}Then poll get_report with report_id=ad_rpt_xyz until status="ready".
Notes#
- Idempotency: Adlyse hashes
(org, user, period, template_version, params)into an idempotency key on the underlying row. Repeated identical calls within a short window deduplicate. - Approval lane: if the template requires review, the status path is
pending → rendering → pending_review → approved/rejected → ready. The initialgenerate_reportresponse is the same; poll for the final state.
See also#
list_report_templates— discover available template keysget_report— poll for completion and fetch PDF