Limits over the API
Read, set, change, reset and remove volume limits over REST on advertisers, campaigns, banners, sites and placements — the endpoints, date formats, per-cap permissions and error answers.
Limits can be read, set, changed, reset and removed over REST on all five levels. The full parameter list is in Targeting, capping and limits via API; what follows is how the endpoints behave.
Who this is for
- Integrators who manage caps from their own system instead of the Limits card. The caller needs the same access to the entity and the same per-cap permissions as on the card — see Set volume limits and budgets for what each role is granted by default.
Endpoints
| Level | Endpoints |
|---|---|
| Advertiser, campaign, banner | GET / DELETE /rest-api/{advertiser|campaign|banner}/{id}/limits.do, POST …/limits/set.do, …/limits/update.do, …/limits/reset.do |
| Site, placement | The same five operations under /rest-api/site/{id}/limits.do and /rest-api/placement/{id}/limits.do |
How the endpoints behave
set.docreates the limit record when there is none;update.doanswers404and points atset.do. Both merge: a field you leave out keeps its stored value.- Counters cannot be written. The spent figures (
totalImpressionsand the other names without theLimitsuffix) are read-only: sent, they come back inignoredFieldswith the reason and nothing changes.reset.dois the way to zero one. - Dates are
yyyy-MM-dd-HH-mm(oryyyy-MM-dd HH:mm) in GMT+0, or in the caller’s local time withuseLocalTime=trueand atimezoneOffsetin minutes east of UTC. A date the binder cannot read is a400that names both accepted formats and gives an example. A read answers in UTC unless it is passed the sametimezoneOffset; on a local-time limit it then answers the dates in that offset and echoes thetimezoneOffset. - Every cap needs its own permission, the one behind its row on the card (Weekly Clicks
Limit, Monthly Budget …). On an advertiser, campaign or banner, a cap that would change
without its permission is left as stored and comes back in
ignoredFields, itsignoredFieldReasonsentry naming the permission; the caps the role may set are saved. A cap sent with the value it already has needs no permission. On a site or placement a request carrying a cap the role lacks is a403that names the permission, and nothing is saved. A read leaves such a cap out, and on a site or placement lists it infieldsHiddenByPermission. A value outside the column range, or a cap above a longer period’s, is a400naming the field. A missing or deleted entity is a404; missing access to the entity or Manage Capping & Limitations is a403, and so is areset.doof a counter without its permission. - On a site or placement the card’s own rules carry over. Reading needs a share on the site
and Manage Site and Placement Limits (read-only is enough); changing needs update rights and
the same permission; creating or removing the record needs Manage Capping & Limitations.
Budget and opportunity fields do not exist there and answer
400; request caps do.
Corner cases and gotchas
Corner case — “reset all counters” exists only on the demand side of the API. The card has no clear-everything button; each eraser clears exactly its own counter. The advertiser, campaign and banner reset endpoints accept the all-counters value
ALL, which zeroes 22 counters (every delivery counter and the CPA pair) — none of them a requests counter. The site and placement reset endpoints refuseALLand any counter a site limit does not have with a400; name the counters you want cleared. Do not sendALL_ACTION_LIMITSto the reset endpoints either — it is not a supported reset value; name the counters instead.
