Skip to main content
You can use Apostra as the source for a dashboard, a daily reporting job, or an agent that checks campaign performance. Start by deciding whether you need an interactive aggregate, a downloadable aggregate, or a recurring data feed. These are different data products. A CSV aggregate is not a raw event feed, and a notification is not a reporting export.

​
1. Prove access and choose the report

For MCP, call get_status and verify the active account. Inspect the current get_delivery schema before choosing metrics and dimensions.
  • A Buyer Account uses report: "campaign_delivery".
  • A Seller Account uses report: "delivery" for seller-reported delivery, or report: "margin" for its cumulative spread ledger.
  • An integrated Media Company can also read campaign_delivery for its own supported advertiser, campaign, or media-buy scope. This does not grant a Seller credential general access to Buyer REST reporting.
For REST, use a credential authorized for the relevant Buyer API. A v3 MCP OAuth token cannot be used on REST. See Authentication.

​
2. Read a bounded delivery window

For a Buyer Account, call get_delivery:
Replace the campaign ID and dates with the scope you intend to read. Explicit date ranges are inclusive UTC dates and support at most 90 days. Buyer campaign delivery also supports range: {"lifetime": true}; a packageId filter requires a bounded range instead. Use the buyer or seller reference for the report available to your account. Follow the returned pagination contract until all requested rows are read. Preserve report type, account and resource scope, requested dimensions, returned period, and the time of extraction with the results.

​
3. Preserve what the data means

Your consumer should carry coverage, warnings, finality, and unavailable values alongside the numbers. Do not turn a missing source value into zero or describe seller-reported delivery as independent buyer measurement. Finality alone is not evidence that an amount is eligible for billing. For Buyer campaign delivery, totals covers every matched row, not just the current page. Do not add the repeated totals from successive pages. Mixed currency results do not convert currencies: monetary totals can be unavailable while counts remain usable. Keep each row’s currency with its monetary values. Seller delivery pages are live reads. A cursor continues the query but does not freeze a historical snapshot. If your application needs a reproducible extract, store the completed extract and its query metadata in your own system and label when it was read.

​
4. Run a repeatable extraction job

For a daily dashboard or warehouse load, your worker can:
  1. Load the account, report, requested dimensions, and last completed date window from its checkpoint.
  2. Read each bounded window and all its pages into a staging destination.
  3. Check warnings and coverage, then publish the completed window. Use a key containing its account, dimensions, date, and currency so a retry replaces the same data rather than appending duplicates.
  4. Advance the checkpoint only after the destination has accepted the complete window.
  5. Re-read a recent overlap window according to your source’s correction and freshness needs. Retain when each extract was observed.
Delivery reaches reporting through supported seller webhooks, source polling, and downstream aggregation. A successful API response is not a promise that a seller has reported every event or that the result is real-time. Review the reporting data flow for your sources. Buyer REST reporting is day-grain; an hourly job does not make that endpoint an hourly delivery report.

​
5. Choose CSV export or scheduled cloud delivery

For a CSV aggregate, use the current v2 REST reporting contract:
This example requests the credential’s available reporting scope. Add the documented advertiser or campaign filters when the job should cover a narrower scope. The response returns downloadUrl, expiresAt, fileName, and rowCount. Fetch the file in the consuming service; the signed URL is a bearer credential and must not appear in logs or public dashboards. See CSV export. For a recurring cloud feed, follow Data Delivery: grant the documented storage permissions, register an advertiser-scoped credential, wait for its asynchronous validation, then attach outputs for the supported data types and cadence. Confirm that objects arrive in your bucket or container before treating the feed as working. Data Delivery uses v2 configuration today; it is not a generic v3 export tool. Data Delivery credentials and outputs are full-replace arrays. Read the current configuration and preserve entries you intend to keep before updating it.

​
Use notifications to resume work

For a human operator, use the existing notification channels and inbox. Registered external buyer agents have separate machine-notification administration. Use the documented event and delivery contract for that connection, and re-read the referenced object before taking the next action. Do not use authored notification subscriptions as a scheduler for this pipeline: their schedule and condition triggers do not execute yet. A Slack incoming webhook is a notification destination, not a machine-readable export of all campaign changes. Your own scheduled poll or the supported Data Delivery schedule is the working path for recurring extraction.

​
Verify before connecting a dashboard

Test the consumer with empty data, an unavailable metric, mixed currencies, and more than one page. Prove that rerunning a completed window does not duplicate rows. Then read a known live campaign and compare its scope, period, and totals with the same report in Apostra. Fixture tests verify your consumer; this live comparison verifies access and the meaning of the selected report.