The Opteo API lets you retrieve and manage your Opteo data programmatically. It follows REST principles and is currently invite only.
To request an API key, please contact [email protected].
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 Authorization header on each HTTP request:
Authorization: Bearer {YOUR_TOKEN}
API tokens are issued by the Opteo team on request. All requests must be made over HTTPS. Calls over plain HTTP will fail.
Errors
The Opteo API uses standard HTTP response codes. Successful requests return a 200. Errors return a code in the 400 (client) to 500 (server) range, along with a short message describing what went wrong. For example, calling an endpoint for an account that isn't active in Opteo returns:
{
"status": 403,
"message": "Forbidden - Client not active in Opteo, this may be due to a billing problem, or because it isn't selected in Linked Accounts"
}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).
Available endpoints
For full request and response details, including code examples, see the complete documentation on GitHub.
Customers - list your ad accounts, check linking state, manage connected team members, and update changelog email settings.
Budgets - get or update an account's monthly budget target. This is the figure Opteo uses for Budget Pacing and budget alerts. It does not change any budgets in Google Ads.
Performance mode - get or update whether an account is evaluated in CPA or ROAS mode.
Performance goals - get or update an account's target CPA or ROAS, the evaluation cycle, and the cycle start date.
Improvements - retrieve the active and completed Improvements for an account. Some newer Issues and Alerts (such as Disapproved Ads, Broken Links, and Spelling Errors) are only available in the Opteo interface, not via the API.
Alerts - retrieve performance monitoring Alerts for one account or all accounts, covering the last 90 days.
Reports - list all reports across your accounts and download them as PDFs.
GAQL - run Google Ads Query Language queries to pull data directly from Google Ads.
Users - list the team members in your Opteo account, including each member's user ID.
Run Agent - run an Opteo AI agent (the same AI behind Opteo AI Chat) against an account and get its response back. Returns immediately and posts the result to a callback URL when the agent finishes.