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. With 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, the organization's currency, the locations it serves customers in, its monthly ad_budgets per platform, and the intel Glitch has collected about it from outside its own data, each kind marked stale once it is out of date. Answers not_found until the organization has a business profile.

The business's saved competitors, closest first: each one's id, name, website, closeness from 0 to 1, and what Glitch's research found (industry, audience, location, size, headquarters, founding year, social profiles and a description). All of them come in one response. Needs organizations:read.

What the presented credential can do: scopes, the scopes it can use in at least one organization, and organization, the slug an API key is bound to, null for an OAuth connection that acts in every organization its user belongs to. Needs no scope.

List campaigns with their seven day numbers. Each row says its platform, and metrics_status says whether its numbers are in Glitch yet, available or not_available, with metrics_message saying why when they are not. A Google campaign's type is prospecting, brand, competitor, icp, hipo or location; a Meta campaign's is scaling, testing or retargeting, with its leads counted as conversions.

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

// 200
{
  "campaigns": [
    { "platform": "google", "slug": "acme-prospecting", "name": "Prospecting", "type": "prospecting",
      "state": "live", "budget": 40.00, "spend_7d": 212.40, "conversions_7d": 10, "cpa_7d": 21.24,
      "created_at": "2026-05-02T10:11:04Z", "metrics_status": "available", "metrics_message": null },
    { "platform": "google", "slug": "acme-brand", "name": "Brand", "type": "brand",
      "state": "live", "budget": 20.00, "spend_7d": 120.20, "conversions_7d": 19, "cpa_7d": 6.33,
      "created_at": "2026-04-14T09:02:51Z", "metrics_status": "available", "metrics_message": null }
  ],
  "total": 2, "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 when the performance numbers were last refreshed, and is null for a campaign that has never been in Google Ads. A Meta campaign's slug answers with its objective, budget and ad sets instead.

// GET /v1/organizations/acme/campaigns/acme-prospecting
{
  "slug": "acme-prospecting", "name": "Prospecting", "type": "prospecting", "state": "live",
  "spend_7d": 212.40, "conversions_7d": 10, "cpa_7d": 21.24, "created_at": "2026-05-02T10:11:04Z",
  "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.

An executed change is all or nothing: Google Ads and Glitch both take it or neither does, and its action_id undoes it. A call that sends only values the campaign already has is refused with validation_error, because there would be nothing to undo. The executed call can also be refused before anything is sent, and then nothing changes. If another change to the campaign is still being sent to Google Ads, the answer is sync_conflict: retry when it has finished. If the campaign was changed by something else while the call was being made, the answer is also sync_conflict: read the campaign again, then resend. If one of the campaign's ads has a funnel stage with fewer than 3 headlines or 2 descriptions, the answer is validation_error naming the ad and the stage: add the copy in the dashboard, then resend. A call made while the campaign's Google connection cannot be used is a validation_error too: reconnect Google in the dashboard.

# 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. A campaign that has been published can't be set back to draft: pause it instead. Asking for it is a validation_error.

Launching needs a paid plan: an organization on the free plan is answered payment_required. It also 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 when Google Ads cannot be read the launch is refused with the same error. A campaign's first launch also runs the checks the dashboard runs before approval: a website URL, a location or radius, valid sitelinks and callouts, at least one ad, valid headlines and descriptions on every ad, 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.

An executed call is all or nothing: Google Ads and Glitch both take every term or neither does, and its action_id undoes it. Terms the campaign already excludes are left out; a call where every term is already excluded is refused with validation_error. If another change to the campaign is still being sent to Google Ads, or the campaign changed while the call was being made, the answer is sync_conflict: retry once it has finished, or resend. If one of the campaign's ads has a funnel stage short of headlines or descriptions, or the campaign's Google connection cannot be used, the answer is validation_error saying what to fix. Nothing changes when a call is refused.

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. availability says which ad accounts the numbers cover; each by_campaign row also carries clicks, impressions, CTR, CPC, ROAS, conversion value and its search impression share with the share lost to rank and to budget.

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

// 200
{
  "platform": "google",
  "period": { "from": "2026-07-01", "to": "2026-07-07" },
  "availability": { "status": "available", "message": null, "unavailable_accounts": [] },
  "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-prospecting", "spend": 212.40, "clicks": 702, "impressions": 11230,
      "conversions": 10, "cpa": 21.24, "search_impression_share": 0.41 },
    { "slug": "acme-brand", "spend": 120.20, "clicks": 318, "impressions": 2104,
      "conversions": 19, "cpa": 6.33, "search_impression_share": 0.92 }
  ]
}

What people actually searched, dearest first, with availability as on performance.

// 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 }
  ],
  "availability": { "status": "available", "message": null, "unavailable_accounts": [] },
  "total": 412, "next_cursor": "djE6MjA="
}

Every campaign in the account that spent in the period or is enabled, most spent first: its type, status, serving status, bidding strategy, budget and budget period with Google's recommended_budget, its start date, glitch_campaign (the slug when Glitch runs it), its totals and search impression share over the period, and by_month. by_device gives the account's totals by device.

Every keyword with traffic in the last 90 days, most spent first, with its quality score from 1 to 10 and its three parts (expected_ctr, ad_relevance, landing_page_experience, each null until Google rates it), and first_page_cpc.

What people searched across every campaign in the account, most spent first.

The pages the account's ads sent people to over the last 90 days, per campaign, most spent first.

Every conversion action in the account, the kind of result it counts, and how many it counted over the last 90 days, most counted first. All of them come in one response.

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-08T07: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 the Strategic Plan, or rewrite it. Asynchronous. Needs reports:generate. A request made while the plan is being written answers with the generation already under way. 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, and documents already uploaded to the organization are always included. The url opens the plan in Glitch once it is written.

Writing a plan 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_5137", "task_tracking_id": 90412,
  "url": "https://app.glitchads.ai/reports/5137?org=acme"
}

The organization's Strategic Plan as a list of one, or none before the first is written. The body stays on the detail read. Answers not_found until the organization has a business profile.

The plan, by its id. While a first plan is still being written markdown is null; if it failed, error says why. A plan being rewritten answers with the text it has until the new one is done.

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

What became of a queued change. status is pending, approved, rejected, failed or withdrawn, and only pending ever changes. approved carries the result; rejected and failed carry an error saying why, which is expired for a change nobody acted on within seven days. withdrawn means it was taken back before anyone decided, because what it would change stopped serving or the detector behind it stopped finding the problem. decided_at is when it stopped being pending. 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", "decided_at": "2026-09-20T10:02:40Z",
  "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 a null recommendation_id. 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": 39.86
}

What the optimisation engine and detector runs have proposed. Changes held for approval on a campaign also appear here, with type api_write; they are approved or rejected in Glitch, not applied through this API. 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": 1, "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. Only a pending recommendation can be applied; one already applied, dismissed or undone answers validation_error. 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, what made it, and reason, why it was made when that was recorded. Filter with from, to and source, and platform, google by default or meta. 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", "platform": "google",
      "detail": "Excluded 'free ads course' (phrase)",
      "reason": "Spent 18.60 over 14 days with no conversion", "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 apart from the event id. Each event records its id, the time, request id, operation, path, status code, error code, actor type, the user's account id, 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 completed strategy task carries the strategy id and its url instead. 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, google_ads_connection_broken or payment_required, and a message saying what to do next. Four 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. payment_required: the job would have put a campaign live, which an organization on the free plan cannot do; nothing was changed, and nothing will be until the plan is upgraded.

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": "live", "synced_at": "2026-07-08T09:14:02Z" }
}