REST API reference

The organizations this credential can act in, each with your role, plan and currency. Exactly one for an API key; every organization the user belongs to for an OAuth token. Glitch adops staff also see every client organization assigned to their team, read only: those rows carry access adops_team and no role. adops_team names the team responsible for an organization on any row that has one, so results can be grouped by team.

// GET /v1/organizations
{
  "organizations": [
    { "slug": "acme", "name": "Acme Ltd", "role": "owner", "plan": "SMB", "currency": "EUR",
      "access": "membership", "adops_team": null },
    { "slug": "bright-dental", "name": "Bright Dental", "role": null, "plan": "SMB", "currency": "GBP",
      "access": "adops_team", "adops_team": { "name": "Realglitch" } }
  ],
  "total": 2,
  "next_cursor": null
}

Plan, currency, spend limits and ad accounts. max_spend is the organization's monthly spend cap, null when none is set, and api_budget_change_limit_pct is the most one call may move a budget. ad_accounts lists the Google Ads accounts the organization's campaigns use or its members have selected, each linked, pending or not_linked. access says how this credential reaches the organization, membership or adops_team, and adops_team names the Glitch team responsible for it, null when there is none.

// GET /v1/organizations/acme
{
  "slug": "acme", "name": "Acme Ltd", "plan": "SMB", "currency": "EUR",
  "max_spend": 5000.00, "api_budget_change_limit_pct": 25,
  "ad_accounts": [ { "id": "8932210042", "platform": "google", "status": "linked" } ],
  "access": "membership", "adops_team": null
}

The business context Glitch has learned: its URL, brand name, description, products, ideal customer profiles, competitors and trust signals. Answers not_found until the organization has a business profile.

List campaigns with their seven day numbers.

curl "https://api.glitchads.ai/v1/organizations/acme/campaigns?state=live" \
  -H "Authorization: Bearer $GLITCH_API_KEY"

// 200
{
  "campaigns": [
    { "slug": "acme-prospecting", "name": "Prospecting", "type": "prospecting", "state": "live",
      "budget": 40.00, "spend_7d": 212.40, "conversions_7d": 18, "cpa_7d": 11.80,
      "created_at": "2026-05-02T10:11:04Z" }
  ],
  "total": 4, "next_cursor": null
}

Full campaign detail. keywords_count includes paused keywords. negative_keywords_count counts the active exclusions on the campaign and on its ads, including ones added through this API. last_synced_at is null for a campaign that has never been in Google Ads.

// GET /v1/organizations/acme/campaigns/acme-prospecting
{
  "slug": "acme-prospecting", "name": "Prospecting", "type": "prospecting", "state": "live",
  "budget": 40.00, "target_cpa": 15.00, "goal": "prospecting", "website_url": "https://acme.co",
  "ads_count": 3, "keywords_count": 84, "negative_keywords_count": 31,
  "last_synced_at": "2026-07-08T06:00:12Z"
}

Generate a complete campaign from a website. Always a draft: going live is a separate state call. Asynchronous. The draft starts from the business profile's description and target locations, in the Google Ads account selected for the organization. It is refused while the business profile is still being analysed, or when no Google Ads account is selected for the organization.

The response names the new draft's campaign slug and its url, the campaign's page in Glitch. The link opens the campaign in its own organization, even for someone who last worked in another one.

curl -X POST https://api.glitchads.ai/v1/organizations/acme/campaigns \
  -H "Authorization: Bearer $GLITCH_API_KEY" -H "Content-Type: application/json" \
  -d '{"website_url":"https://acme.co","type":"brand","budget":25.00}'

// 202
{ "task_tracking_id": 5521, "status": "queued", "campaign": "Xk2pQ9LmT4",
  "url": "https://app.glitchads.ai/campaigns/google/Xk2pQ9LmT4?org=acme" }

Add a new ad (a Google ad group) to an existing campaign, generated from a landing page. Asynchronous, with no dry_run. On a live campaign the finished ad is pushed to Google Ads and starts serving; on a draft it waits with the campaign. It returns the new ad_id but no action_id: remove an ad in the dashboard. Imported external campaigns and competitor campaigns are not accepted, and neither is a campaign with no linked Google Ads account or an incomplete Google connection.

curl -X POST https://api.glitchads.ai/v1/organizations/acme/campaigns/acme-prospecting/ads \
  -H "Authorization: Bearer $GLITCH_API_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://acme.co/pricing"}'

// 202
{ "task_tracking_id": 5533, "status": "queued", "ad_id": 912 }

Update name, budget or target CPA. Only the fields you send change. One call may move a budget by at most api_budget_change_limit_pct, 25 by default; a breach answers budget_cap_exceeded with allowed_min and allowed_max. Where the organization has a max_spend, the daily budgets of all its campaigns, drafts and paused ones included, times 30 must stay within it; a breach answers budget_cap_exceeded with monthly_cap and allowed_max_daily. A dry run reports either breach as within_limits: false instead.

# preview: dry_run defaults to true, so this changes nothing
curl -X PATCH https://api.glitchads.ai/v1/organizations/acme/campaigns/acme-prospecting \
  -H "Authorization: Bearer $GLITCH_API_KEY" -H "Content-Type: application/json" \
  -d '{"budget":48.00}'

// 200 (dry run)
{ "dry_run": true, "would_change": { "budget": { "from": 40.00, "to": 48.00 } },
  "within_limits": true }

// 200 (executed, with "dry_run": false)
{ "applied": true, "action_id": "act_9077",
  "changed": { "budget": { "from": 40.00, "to": 48.00 } } }

Pause, resume or launch. An executed change syncs to Google Ads in the background through the same pipeline as the dashboard, and answers straight away with a task_tracking_id to poll and an action_id to undo. The campaign must be linked to a Google Ads account the credential's user can access.

Launching refuses a campaign with no budget, and one whose budget would take the organization over its monthly spend cap. It also checks Google Ads for changes made there since the last sync and answers sync_conflict if it finds any; the check covers syncs in the last 30 days and is skipped if Google Ads cannot be read. A campaign's first launch also runs the checks the dashboard runs before approval: a location or radius, valid sitelinks and callouts, at least one ad with valid headlines and descriptions, and a keyword on every ad. The error names the first thing missing. A dry run runs the same checks and reports the first one that fails as blocked_by, which is null when the transition would go through; the sync conflict check runs only on the executed call.

// 200 (dry run)
{ "dry_run": true,
  "would_change": { "state": { "from": "draft", "to": "live" } },
  "blocked_by": "Set a daily budget greater than 0 before launching." }

// 200 (executed)
{ "accepted": true, "task_tracking_id": 6102, "action_id": "act_9120" }

The keywords on a campaign, with thirty day performance.

// 200
{
  "keywords": [
    { "text": "ppc management", "match_type": "phrase", "state": "enabled",
      "clicks_30d": 140, "cost_30d": 168.20, "conversions_30d": 11, "avg_cpc": 1.20 }
  ],
  "total": 84, "next_cursor": "djE6MjA="
}

Exclude terms across the campaign. On a live campaign the exclusions go to Google Ads first; on a draft they wait with the campaign.

curl -X POST https://api.glitchads.ai/v1/organizations/acme/campaigns/acme-prospecting/negative-keywords \
  -H "Authorization: Bearer $GLITCH_API_KEY" -H "Content-Type: application/json" \
  -d '{"keywords":["free ads course","ppc jobs"]}'

// 200 (dry run, the default)
{ "dry_run": true, "match_type": "phrase",
  "would_apply": [ { "op": "add_negative_keyword", "term": "free ads course", "match_type": "phrase" },
                   { "op": "add_negative_keyword", "term": "ppc jobs", "match_type": "phrase" } ] }

// 200 (executed, with "dry_run": false)
{ "applied": true, "action_id": "act_9124", "added": 2, "match_type": "phrase" }

Metrics over a date range, grouped and compared against the previous period.

curl "https://api.glitchads.ai/v1/organizations/acme/performance?from=2026-07-01&to=2026-07-07" \
  -H "Authorization: Bearer $GLITCH_API_KEY"

// 200
{
  "period": { "from": "2026-07-01", "to": "2026-07-07" },
  "summary": { "spend": 412.10, "impressions": 18740, "clicks": 1143, "ctr": 0.061,
               "conversions": 31, "cpa": 13.29, "roas": 4.2,
               "vs_previous": { "spend": "+4%", "conversions": "+12%", "cpa": "-8%" } },
  "by_campaign": [
    { "slug": "acme-brand", "spend": 120.20, "conversions": 19, "cpa": 6.33 },
    { "slug": "acme-prospecting", "spend": 212.40, "conversions": 10, "cpa": 21.24 }
  ]
}

What people actually searched, dearest first.

// 200
{
  "search_terms": [
    { "term": "ppc management for dentists", "campaign": "acme-prospecting",
      "clicks": 31, "cost": 42.10, "conversions": 4 },
    { "term": "free ads course", "campaign": "acme-prospecting",
      "clicks": 22, "cost": 18.60, "conversions": 0 }
  ],
  "total": 412, "next_cursor": "djE6MjA="
}

List reports of a type, newest first. Each row carries the id, type and generated_at; read one to get its body.

The most recent one, without listing first. not_found when there is none yet.

// GET /v1/organizations/acme/reports/weekly/latest
{
  "id": "rep_2841", "type": "weekly", "generated_at": "2026-07-06T07:00:00Z",
  "markdown": "# Weekly performance\n\nSpend 412.10 EUR (+4%)…"
}

One specific report.

Generate the report for the current period. Asynchronous, and it counts as a write. weekly only. An organization holds one report per period and type: generating again rebuilds that report in place, and it keeps its id.

Write a new strategy. Asynchronous. Needs reports:generate. Send documents to put your own material in front of it: each carries a name and content as markdown or plain text, at most five, 20,000 characters each.

Writing a strategy changes nothing else: no campaign is touched, and the organization's business profile is left as it stands.

// POST /v1/organizations/acme/strategy
{ "documents": [{ "name": "Q4 joint impact plan", "content": "# Plan\n\nGrow paid search 30%." }] }

// 202 Accepted
{
  "status": "queued", "strategy": "str_18", "task_tracking_id": 90412,
  "url": "https://app.glitchads.ai/reports/strategy?org=acme&strategy_run=18"
}

List the organization's strategy documents, newest first. Bodies stay on the detail read.

One document, by its id. While it is still being written markdown is null; if it failed, error says why.

// GET /v1/organizations/acme/strategy/str_18
{
  "id": "str_18", "status": "succeeded", "title": "Q4 strategy",
  "created_at": "2026-09-20T09:14:02Z", "finished_at": "2026-09-20T09:21:47Z",
  "url": "https://app.glitchads.ai/reports/strategy?org=acme&strategy_run=18",
  "markdown": "# Q4 strategy\n\nSpend where intent is…", "error": null
}

What became of a queued change. status is pending, approved, rejected or failed, and only pending ever changes. A person has to act, so poll slowly.

// POST /v1/organizations/acme/campaigns/spring-sale/negative-keywords
{ "keywords": ["free"], "dry_run": false }

// 202 Accepted
{
  "error": {
    "code": "approval_required",
    "message": "This organization queues API writes for human sign-off. The change is pending as recommendation 'rec_812' in the dashboard's approval queue; poll /v1/queued-writes/rec_812 for the outcome.",
    "doc_url": "https://glitchads.ai/docs/errors#approval_required",
    "queued_recommendation_id": "rec_812"
  }
}

// GET /v1/queued-writes/rec_812, once somebody has approved it
{
  "id": "rec_812", "status": "approved", "operation": "add_negative_keywords",
  "requested_at": "2026-09-20T09:14:02Z", "result": { "action_id": "act_4471", "added": 1 }
}

Run one detector. It never changes the campaign. For a campaign that runs in Google Ads, findings that can be acted on are saved as a pending recommendation, replacing the details of any pending recommendation of the same type on that campaign, and carry its recommendation_id. A draft's findings, and keyword_count findings, carry none. estimated_monthly_saving is left out when the detector does not compute one.

curl -X POST https://api.glitchads.ai/v1/organizations/acme/campaigns/acme-prospecting/detect \
  -H "Authorization: Bearer $GLITCH_API_KEY" -H "Content-Type: application/json" \
  -d '{"detector":"negative_keywords","options":{"days":14}}'

// 200
{
  "detector": "negative_keywords",
  "findings": [ { "term": "free ads course", "match_type": "phrase", "cost_14d": 18.60, "clicks": 22,
                  "conversions": 0, "recommendation_id": "rec_4417" } ],
  "estimated_monthly_saving": 41.20
}

What the optimisation engine and detector runs have proposed. Filter with campaign and status, which is pending by default and also takes applied or dismissed, meaning rejected by a person. A recommendation applied and then undone matches none of the three. estimated_monthly_saving is always null today.

// 200
{
  "recommendations": [
    { "id": "rec_4417", "type": "negative_keywords", "campaign": "acme-prospecting",
      "summary": "Exclude 'free ads course'", "estimated_monthly_saving": null,
      "created_at": "2026-07-08T08:02:11Z" }
  ],
  "total": 6, "next_cursor": null
}

Apply one pending recommendation. dry_run defaults to true: the preview lists the operations it would run, or one summary operation when the recommendation does not itemise them. A recommendation applied in the last five minutes cannot be applied again, and a budget recommendation meets the same budget limits as PATCH. Needs recommendations:apply.

// 200 (dry run)
{ "dry_run": true,
  "would_apply": [ { "op": "negative_keywords", "summary": "Exclude 'free ads course'" } ],
  "estimated_monthly_saving": null }

// 200 (executed)
{ "applied": true, "action_id": "act_8841", "action_ids": [ "act_8841" ] }

Reverse an executed action, whichever endpoint made it. Needs recommendations:apply. Undoing a state change starts the reverse transition in the background. restored lists what was reversed. Idempotent: undoing an action already undone returns an empty restored, spends no write quota and changes nothing.

// 200
{ "undone": true, "action_id": "act_8841",
  "restored": [ "Reversed: Excluded 'free ads course' (phrase)" ] }

// 200 (already undone: nothing ran)
{ "undone": true, "action_id": "act_8841", "restored": [] }

The action log: every change, and what made it. Filter with from, to and source. Needs audit:read, which only an Owner's credential can carry.

source says what kind of change it was: dashboard for a direct edit, including a PATCH, state change or negative keywords sent through this API, and engine for an applied recommendation, whoever applied it. api is accepted as a filter and matches nothing today. To find who made a change, read the actor block: type is api_key for a key, with prefix its environment prefix and last four characters and user its creator; user for a person, including one acting through an OAuth connection; and engine for Glitch itself.

// 200
{
  "actions": [
    { "id": "act_8841", "at": "2026-07-08T09:14:02Z", "source": "engine",
      "actor": { "type": "api_key", "prefix": "glads_live_3f2a", "user": "dave@glitchads.ai" },
      "op": "add_negative_keyword", "campaign": "acme-prospecting",
      "detail": "Excluded 'free ads course' (phrase)", "undone": false }
  ],
  "total": 129, "next_cursor": "djE6MjA="
}

The access trail, for compliance. Owner only, answering role_denied to anyone else, and needs audit:read. Filter with from and to; without from the export covers the 30 days up to to, or up to now. format is json by default, a total and the events, and also takes csv with the same columns. Each event records the time, request id, operation, path, status code, error code, actor type, user, key prefix and last four characters, IP address and user agent. It includes failures, not only successful changes, and is not paginated.

curl "https://api.glitchads.ai/v1/organizations/acme/audit/export?from=2026-06-01&format=csv" \
  -H "Authorization: Bearer $GLITCH_API_KEY" -o acme-audit.csv

The state of any asynchronous job. Poll every 2 to 5 seconds until it is completed or failed; until then it is running. progress is 0 until the task completes, then 100. A completed task on a campaign, such as a campaign or ad creation, carries a result with the campaign slug and its url in Glitch, and a state change adds the state and synced_at. A report task carries none. A failed task carries an error with a reason, one of task_error, stuck_timeout, killed_by_restart, worker_shutdown, setup_required, google_ads_refused or google_ads_connection_broken, and a message saying what to do next. Three are to handle differently. setup_required: the job cannot run until something is connected, so it will fail the same way until somebody does that, and retrying is wasted. google_ads_refused: Google Ads declined the change and the message carries Google's own reason (a trial campaign whose status cannot change, for one); the campaign has to change in Google Ads first. google_ads_connection_broken: the job could not read Google Ads because the Google login behind the organization's account was revoked or deleted. It fails the same way until the account's owner reconnects Google Ads in Glitch, so retrying before that is wasted.

This one needs no scope of its own: any credential that can act in the task's organization can poll it, and any other id answers not_found.

// GET /v1/task-tracking/6102
{
  "task_tracking_id": 6102, "type": "CAMPAIGN_STATE_UPDATE", "status": "completed",
  "progress": 100,
  "result": { "campaign": "acme-prospecting",
              "url": "https://app.glitchads.ai/campaigns/google/acme-prospecting?org=acme",
              "state": "paused", "synced_at": "2026-07-08T09:14:02Z" }
}