Skip to main content

Opteo API

A reference guide to what's available via the Opteo API

Written by Shaquira Jeyasingh

The Opteo API lets you retrieve and manage your Opteo data programmatically. It follows REST principles and is currently invite only.

To request access, contact [email protected]. API access is currently only available for annual subscriptions.

The base URL for all requests is https://api.opteo.dev/v0. Full request and response documentation, including code examples, is available at github.com/Opteo/api.

Authentication

All requests must be authenticated using a bearer token. Set an Authorisation header on each HTTP request:

Authorisation: Bearer {YOUR_TOKEN}

API tokens are issued by the Opteo team upon request. All requests must be made over HTTPS. Calls over plain HTTP will fail.

A note on customer IDs

Endpoints scoped to a specific ad account use a {customer-id} in the URL. This is the Google Ads customer ID, the ten-digit number found in Google Ads, not an Opteo ID. You can also retrieve a list of your customer IDs via the Customers endpoint (see below).

Improvements

The improvements endpoint returns active Google Ads Improvements for a linked ad account, the same list shown in the Active tab in Opteo, sorted by priority. Completed and dismissed Improvements are not returned.

GET /v0/customers/{customer-id}/improvements

A completed improvements endpoint is also available:

GET /v0/customers/{customer-id}/improvements/completed

Each improvement in the response includes its ID, title, type, recommended action, creation timestamp, and location within the ad account. Over 40 Google Ads Improvements are currently available. See the full list on GitHub.

Six legacy Issues are also returned by this endpoint: Apply Exclusion List, Apply Negative List, Fix Broken Link, Fix Broken Sitelink, Fix Keyword Conflicts, and Fix Modified Broad Negatives.

Note: The newer Issues and Alerts - including Disapproved Ads, Disapproved Keywords, Broken Links, Empty Campaigns, Empty Ad Groups, and Spelling Errors - are not available via the API. They are only accessible in the Opteo interface.

Alerts

The alerts endpoint returns performance monitoring alerts, the same notifications shown in the Alerts panel in Opteo. Results are sorted by creation date and cover the last 90 days, up to 500 alerts.

GET /v0/alerts returns alerts across all linked ad accounts.

GET /v0/customers/{customer-id}/alerts returns alerts for a specific ad account.

The following alert types are available:

  • budget: budget pacing notification

  • conversion: a conversion record was achieved

  • delta: an unexpected change in cost or performance was detected

  • impressionsFlatline: impressions dropped to zero

  • conversionActionsFlatline: conversion tracking stopped firing

  • over_budget: the ad account has exceeded its budget

  • record_days: a record number of days of performance was achieved

  • smart_bidding_experiment: a smart bidding experiment has results to review

Other endpoints

Customers: list all ad accounts accessible with your API token, check linking state, manage which team members are connected to an ad account, and update changelog email settings.

Budgets: get or update the monthly budget target for a linked Google Ads ad account. This is the target Opteo uses for Budget Pacing and budget alerts. It does not change any budgets in Google Ads.

Performance mode: get or update whether an ad account is evaluated in CPA or ROAS mode. This affects how Opteo assesses campaign performance and which Improvements it surfaces.

Performance goals: get or update the performance targets for an ad account, including your target CPA or ROAS amount, the evaluation cycle (day, week, month, quarter, or year), and the cycle start date.

Reports: list all reports across your linked ad accounts and download individual reports as PDFs.

GAQL: run arbitrary Google Ads Query Language queries against a linked Google Ads ad account to retrieve data directly from Google Ads.

Did this answer your question?