Taboola Ads API: Endpoints, Limits & Use Cases
The Taboola Ads API is the Backstage API, a set of endpoints for managing sponsored content campaigns and pulling reports from your own systems. It fits advertisers and agencies running more campaigns than anyone wants to edit by hand. Most teams start with the reporting endpoints, then add campaign management once the data flow holds.
Why trust our Taboola Ads API guidance:
We’re 28 specialists with 190 plus combined years of marketing experience. We’ve delivered 90 plus AI powered marketing automations, and a lot of that work runs through ad APIs. We see where they break.
Need help with a Taboola Ads API build?
Get in touch if you’d rather hand the wiring to a team that already runs it. Our Taboola Ads management work covers the reporting pipeline and the campaign automation sitting behind it. Reach out and we’ll map the fit.
What Is the Taboola Ads API, and What Can You Build With It?
The Taboola Ads API, documented as the Backstage API, lets you manage campaigns, run reports, and automate account tasks from your own software. Most endpoints need an Account ID, so the first thing to settle is which account you’re calling.
Think of it as a second way into the same account. Whatever your team does by clicking, the API can do on a schedule instead.
- Reporting pulls: campaign numbers into your warehouse or BI tool
- Bid and budget rules: changes that run without anyone logging in
- Bulk edits: creative and targeting changes across many campaigns at once
- Alerting: a message when spend or delivery moves outside your band
- Client dashboards: live numbers for the people paying the invoice
Not every account needs it. Under a handful of campaigns, a manager still moves faster in the interface. That is where hands on Taboola Ads agency support does more than any script.
Does Taboola Offer an Open, Public, or Private Ads API?
The docs are public, but the access is not. Anyone can read the Backstage reference online. The credentials that make calls work come from a Taboola account manager, not a signup form.
Who Gets Credentials
The client id and client secret are issued by your account manager. That puts the API behind an existing commercial relationship, which matters if you plan a build before the account exists.
We ask for credentials in the same conversation as account setup. Leaving it later has cost us two weeks more than once, and our Taboola Ads consulting work now opens with that request.
What the Docs Are Open About
Endpoint paths, parameters, and response shapes are all published. Taboola also retired its old Backstage docs repo and now points developers to the reference site. Bookmark the live docs rather than a mirror.
Taboola publishes a machine readable index of those docs at developers.taboola.com/llms.txt. That helps when you want a coding assistant working from the real endpoint list instead of guesswork.
Types of Taboola Ads API Access, Explained
Teams arriving from other ad stacks often ask which API family Taboola uses. The published Backstage reference is organized around REST style endpoints called over HTTPS.
If your last integration leaned on SOAP, a bulk loader, or a streaming feed, plan for a different shape here. Confirm anything beyond the published endpoints with your account manager before you design around it.
| Interface style | What the Backstage reference publishes | How we design around it |
|---|---|---|
| REST over HTTPS | Campaign management and reporting endpoints, keyed to an account id | The primary path for every integration we build |
| SOAP | Not documented in the reference | Wrap the REST calls in your own service layer if internal systems expect SOAP |
| Bulk or batch load | No separate bulk endpoint documented | Loop the standard endpoints with pacing and retries |
| Streaming or webhooks | No streaming feed documented | Poll on a schedule and store the changes yourself |
That table reflects the reference as we read it. Check with your account manager before you rule anything out for good.
How Do You Switch On Taboola Ads API Access?
You request it. Access starts with your Taboola account manager issuing a client id and client secret. The pair comes from a person, not a settings screen.
- Ask your account manager for Backstage API credentials.
- Confirm which account id the credentials belong to.
- Store the secret in your secrets manager, never in the repo.
- Make one read only call to prove the pair works.
Plan for a wait. Credentials have reached us in an hour, and they have taken a week. Teams comparing Taboola Ads alternatives still send this request early, since the wait applies no matter which platform they end up on.
How Do You Find Which Taboola Ads API Version You Are Calling?
Read the URL. Backstage endpoint paths carry the version as a path segment, so a call to backstage/api/1.0 tells you the version without opening a single setting.
That makes version drift easy to audit. Search your codebase for the path segment and you get a full list of what every service calls.
Keep the version in one config value rather than scattered through the code. When it changes you edit one line, not forty.
How Do You Authenticate With the Taboola Ads API Using OAuth?
You use the OAuth 2.0 client credentials flow. Your service posts the client id, the client secret, and a grant type of client credentials to Taboola’s token endpoint. It then sends the returned access token with every call.
Getting a Token
The token request is a POST to backstage.taboola.com/backstage/oauth/token. The body is form encoded, which trips up teams that send JSON by default, and Taboola’s client credentials flow reference lists the exact parameters.
The older password credentials flow is deprecated. If you inherit code that posts a username and password, that is the first thing to replace.
Keeping It Alive
Tokens expire, so cache one and refresh on failure instead of fetching a fresh token per call. We’ve watched integrations spend most of their request budget on token requests alone.
Handle the refresh in one place. A shared client keeps every service on the same token logic and turns rotation into a single change.
Why One Shared Client Saves You Later
Three services with three copies of the token logic will drift within a quarter. One of them will keep a stale cache and nobody will know which until reports go quiet.
A single client also gives you one place to add logging. That is where you find out which job is really burning your request budget.
How Do You Send Your First Taboola Ads API Call?
Pull a report. A realtime campaign summary report is the safest first call, because it reads data without touching a single campaign.
The endpoint takes your account id in the path and a dimension such as by hour, by campaign, or by site. Start and end dates go on the query string.
Run it for one day and one campaign first. If the numbers match what the interface shows, your auth, account id, and date handling are all correct.
It is also the fastest sanity check on data you already report. We run the same call at the start of every Taboola Ads integration to confirm the interface and the API agree.
How Do You Connect Taboola to Other Tools Through the API?
Through a service you own in the middle. The API hands you data and controls. Something on your side still has to call it, shape the response, and write the result somewhere.
Reporting Into a Warehouse
This is the pattern we build most. A scheduled job pulls the previous day’s numbers, writes them to a table, and every dashboard downstream reads from there instead of from Taboola.
Store the raw response as well as the parsed rows. When a number looks wrong six weeks later, the raw payload is the only thing that settles the argument.
The One Field People Forget to Store
Write down when the row was fetched, not just the date it covers. Without it you cannot tell a restated number from a broken job.
We add that column on day one now. It has saved more reconciliation hours than any other habit on this list.
Feeding Bid and Budget Rules
Read performance, apply your rule, write the change back. Keep the read and the write in separate steps so a bad rule cannot fire before you have seen its input.
Log every write with the value before and after. That log is what lets you undo a bad afternoon in minutes.
Feed the right numbers into the right rule and the payoff can be sizable. Taboola’s own Creative Shop program helped one furniture brand land an 8x increase in return on ad spend after reworking its ad copy and visuals.
Joining Taboola to Your Other Channels
Most reporting questions are cross channel, not single channel. Pulling Taboola into the same table as your other paid sources is what a clear read on Taboola versus Outbrain performance actually requires.
Agree on naming before you join anything. A shared campaign naming rule saves more analyst hours than any clever query.
Taboola Ads API Rate Limits, Quotas, and Call Costs
Taboola publishes a limit for the realtime campaign summary report and little else. That endpoint is documented at 10 requests per minute across all dimensions, and going over it returns an HTTP 429.
We treat the rest as unpublished rather than unlimited. A community thread shows conflicting numbers for a general limit, so building against a figure nobody can verify is a poor trade.
| What you are calling | What is documented | How we build for it |
|---|---|---|
| Realtime campaign summary report | 10 requests per minute across dimensions, HTTP 429 over the line | One scheduled pull per account, spaced out, with backoff on 429 |
| Other Backstage endpoints | No published limit we could verify | Assume a low ceiling, queue the writes, retry with backoff |
| Call pricing | No fee on the calls; media stays cost per click or cost per thousand views | Budget engineering time, not call volume |
None of this makes the API expensive to run. It does make it easy to build something that works at ten campaigns and breaks at three hundred. That is where Taboola Ads for ecommerce accounts usually hit the ceiling first.
Common Taboola Ads API Errors, and How to Debug Each One
Most failures we see fall into four buckets, and three of them are configuration rather than code. Reading the status code first saves an hour of guessing.
Error #1: A 401 That Appears Out of Nowhere
This is almost always an expired or cached token. Fetch a fresh one, retry once, and log which service held the stale copy.
If it repeats on the hour, your cache is outliving the token. Shorten the cache window and refresh on failure.
Error #2: A 429 in the Middle of a Report Pull
You crossed the request limit. Back off, wait, and resume instead of retrying in a tight loop.
Spacing pulls across the hour fixes this more often than raising concurrency. We stagger accounts by a minute or two and the problem disappears.
Error #3: An Empty Report That Should Have Rows
Check the date range and the time zone before you check anything else. An account reporting in one zone and a job running in another gives you a clean, empty, entirely correct response.
Then confirm the dimension. Asking for a breakdown that does not apply to your campaigns returns nothing rather than an error.
Error #4: A 404 on a Path That Looks Right
Usually the account id, not the path. Credentials issued for one account will not read another, and the id in the URL has to match the pair you authenticated with.
We keep a one line health check per account and run it before every deploy. That habit came out of Reddit Ads consulting work where three teams shared one integration.
What Security Basics Should Your Team Set Up for the Taboola Ads API?
Treat the client secret like a password to your ad spend. Anyone holding it can move budget, so it belongs in a secrets manager with rotation, access logging, and a named owner.
- Storage: a secrets manager only, never a repo or a shared doc
- Access: the shortest possible list of people and services
- Rotation: a scheduled swap, rehearsed before you need it
- Logging: every write recorded with who or what made it
- Offboarding: rotate the pair when anyone with access leaves
Approval matters as much as storage. Larger accounts running Pinterest Ads management programs usually need a change record for every automated budget move. Bolting that on later is slow work.
Write down who can approve a rule change. An automation with no named owner becomes nobody’s problem the day it misfires.
When Should You Use REST, SOAP, or Bulk Calls With the Taboola Ads API?
REST, every time. Taboola documents one interface style, so the real decision is not which protocol to reach for, it is how often you call the REST endpoints you already have.
That leaves three timing modes, and almost every Taboola integration we build lands in one of them. Picking the wrong one is what makes it fragile.
| Mode | Use it when | What it costs you |
|---|---|---|
| Single call on demand | A person clicks something and waits for an answer | The highest request pressure per result |
| Batched writes | You are changing many campaigns in one pass, your stand in for a Bulk endpoint | Slower feedback, and you need a queue plus retries |
| Scheduled pull | Reporting, alerting, anything that runs on a clock | Data is only as fresh as the schedule |
Reporting belongs on a schedule. Bid changes belong in a queue, and the same split holds on other channels, including the Snapchat Ads management pipelines we run.
Mixing the modes in one job is the common mistake. Keep the read path and the write path in separate services so a slow report cannot block a budget change.
How Do You Test Taboola Ads API Calls Without Touching Live Campaigns?
Carefully, and mostly read only. We have not found a documented sandbox in the Backstage reference. Our practice is to prove the read calls first, then confine write tests to a paused campaign at the smallest budget the account allows.
Reads are safe. Writes are not, and that gap should shape your whole test plan.
Report and lookup calls change nothing, so run them freely against the live account. Compare every result to the interface until the two agree on a full day of data.
Create a paused campaign at the lowest budget the account allows and point every write test at it. Delete it when you are done and keep its id out of production config.
Name the test campaign so nobody mistakes it for real spend. We prefix ours and keep the same convention across accounts, the way we do for Reddit Ads management work.
How Do You Upgrade the API Version Behind a Taboola Flow?
You change the path segment and re test, in that order. Because the version lives in the endpoint URL, an upgrade is a config change plus a verification pass rather than a rewrite.
- Point a copy of the job at the new path.
- Run both versions for a few days and compare the output.
- Move production over once the numbers match.
- Leave the old path in config until you are sure.
Run that comparison on real data, not a sample. Agencies running Pinterest Ads agency reporting cannot explain a number that moved because of a silent version change.
How Do You Keep a Taboola Ads API Integration Running at Scale?
Monitor it like a product, not a script. The integrations that survive have an owner, alerting on missing data, and a habit of checking output against the interface on a schedule.
What to Monitor
Watch for absence, not just errors. A job that returns zero rows without failing is the outage nobody notices until a monthly report looks wrong.
- Freshness: an alert when yesterday’s data has not landed
- Volume: a warning when row counts move outside the usual band
- Errors: 401 and 429 counts trended, not just logged
- Drift: a weekly comparison against the interface
The Alert We Set Up First
Freshness, every time. If yesterday’s rows are missing by mid morning, someone hears about it before a client does.
Everything else can wait a day. A silent gap in the data cannot, because the fix gets harder the further back it sits.
Who Owns It
Name a person, not a team. Integrations decay quietly, and the ones we inherit in poor shape almost always lost their owner rather than their funding.
Fold the review into your regular planning. We attach it to the same cadence as Snapchat Ads consulting reviews so it never becomes a separate meeting nobody schedules.
Taboola Ads API FAQ
If a question here is the one blocking your build, it is worth answering before you write code. The cheapest hour on any API project is the one spent confirming access and account ids.
Disclaimer: This article covers the Taboola Ads API for general information only and is not technical or legal advice. Taboola’s endpoints, limits, and billing terms can change, so verify current details in the official developer documentation before you build. Vantura Marketing is an independent agency, no vendor holds a stake in our business, and this article is neither sponsored nor endorsed by Taboola.
