adjar report

adjar report pulls a single day or a calendar month of performance data from your live ad account — Google Ads or OpenAI Ads — and renders it as a single, data-only markdown file. It is read-only — no config diffing, no writes. The output is designed to be handed to an AI agent (or a human) as objective context: raw counts only, with every derived metric computed from those counts so the math stays auditable.

Syntax

adjar report --config <file> [--day <YYYY-MM-DD> | --month <YYYY-MM>]

Flags

string

required

Path to the root TOML config file (e.g., config/google.toml). The platform and account are read from it.

string

Path to the platform credentials JSON file (google.json or openai.json). Alternatively set ADJAR_CREDENTIALS. See Authentication.

string

A single day to report on (e.g., 2026-04-15). Mutually exclusive with --month — passing both is an error. A single-day report omits the Daily breakdown section, which would be redundant.

string

The calendar month to report on (e.g., 2026-04). Mutually exclusive with --day. Defaults to the last complete month when neither flag is given. Running it for the current month yields a rolling month-to-date snapshot: the frontmatter keeps the nominal full-month range, but the data covers complete elapsed days through yesterday (an in-progress day isn’t reportable), and re-running overwrites it as the month progresses. This matches the Google path.

string

Path to write the report to (e.g., reports/2026-04.google.md). The parent directory is created automatically. Omit to print the report to stdout instead.

Report is read-only

adjar report only runs read-only queries against the platform’s API. It never modifies your account and never touches your local config — run it as often as you like.

Examples

# Last complete month → stdout
adjar report --config config/google.toml

# A specific month → file
adjar report --config config/google.toml --month 2026-04 -o reports/2026-04.google.md

# A single day → file
adjar report --config config/google.toml --day 2026-04-15 -o reports/2026-04-15.google.md

# OpenAI Ads reads identically — the platform comes from the config
adjar report --config config/openai.toml --month 2026-04 -o reports/2026-04.openai.md

What the report contains

Every report opens with YAML frontmatter (platform, month, account, currency, timezone, range, generated_at — single-day reports add a day field), then a title and a one-line scope summary. The sections differ by platform, since each surfaces the metrics its API exposes.

Google Ads
OpenAI Ads

Section	What it shows
Account totals	Impressions, clicks, cost, conversions, and value for the whole account over the period.
Campaigns	The same metrics broken down per campaign.
Conversions by keyword	Day-by-day, which keyword drove each conversion, using all conversions (so secondary actions hidden from the primary Conversions column are included).
Daily breakdown	Per-day metrics across all campaigns. Omitted from single-day (`--day`) reports.
Ad groups	Metrics per ad group.
Ads	Metrics per ad, labeled by name, first RSA headline, or final URL.
Keyword quality	Current Quality Score (1–10) and Google’s Above/Avg/Below ratings for expected CTR, ad relevance, and landing-page experience, plus the landing page each keyword’s ad points at. Active (enabled) keywords only, worst score first.

Section	What it shows
Account totals	Impressions, clicks, cost, conversions, and value for the whole account over the period.
Campaigns	The same metrics broken down per campaign.
Daily breakdown	Per-day metrics across all campaigns. Omitted from single-day (`--day`) reports.
Ad groups	Metrics per ad group.
Ads	Metrics per ad, labeled by name.

OpenAI Ads reports impressions, clicks, cost, and conversions, with CTR, CPC, CPM, conversion rate, cost/conversion, and ROAS derived from them (conversion value is recovered from the API’s ROAS × cost). There are no keyword sections — OpenAI Ads has no keywords, so the Google report’s Conversions by keyword and Keyword quality sections have no OpenAI equivalent.

Reports store raw counts only. Derived metrics — CTR, CPC, CPM, conversion rate, cost/conversion, and ROAS — are computed from those counts at render time, so the stored file stays the source of truth and the math is auditable.

Google Ads only — Quality Score is a current snapshot, not a period-historical value: Google exposes only the latest computed score, and it resets when a keyword is recreated (e.g. a match-type change).

All dates are in your ad account’s time zone — the reporting window, the daily rows, and the day each click and conversion is attributed to. That zone is read from the account and recorded in the timezone frontmatter field, and generated_at carries the same zone’s offset, so day boundaries stay consistent throughout the file.

Next steps

Hand the report to your AI agent alongside your config, then describe the change you want — see the core workflow.

Get Started

Connect a Platform

CLI Reference

Config Reference

adjar report

Syntax

Flags

Report is read-only

Examples

What the report contains

Next steps

​Syntax

​Flags

​Report is read-only

​Examples

​What the report contains

​Next steps

Syntax

Flags

Report is read-only

Examples

What the report contains

Next steps