Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Outbrain Amplify Performance Reporting API
version: '0.1'
description: "This API describes the interfaces for interacting with the Outbrain Amplify product. More information about Amplify can be found on our website: http://www.outbrain.com/amplify.\n\nAt this time we are working with a select number of partners to integrate the Amplify API. To be considered for the Amplify API private beta please register for the beta plan.\n\nIf you have any questions, issues, feature requests as well as if you're interested in announcments of new features, please join our Google group:\n\nhttps://groups.google.com/forum/#!forum/outbrain-amplifyapi\n\nAPI Url\nThe base url for all API end-points is https://api.outbrain.com/amplify/v0.1/\n\nTroubleshooting\nIf you're experiencing any issues or any other difficulties, please post a new topic in our Google group: https://groups.google.com/forum/#!forum/outbrain-amplifyapi\n\nPlease attach to your post the AMPLIFY-REQUEST-ID header from the returned response.\nThis header allows us to identify your unique request and helps us to reply quicker and more efficiently.\n\nUpdates\nAug 13, 2026\nNew: Brand Logo\n\nYou can now read and set a brand logo via the API. A new logoMetadata field has been added to the Marketer entity, and to the PromotedLink entity (available via extraFields=LogoMetaData) so an individual ad can carry its own logo.\n\nFeb 1, 2026\nNew: Section Volume Control for CBS Campaigns\n\nYou can now provide feedback on individual section performance for your CBS Auto mode campaigns (tROAS, tCPA, Max Conversion). This allows you to increase or decrease traffic volume from specific sections based on your own external data, such as LTV or ROAS. A new volumeControl object has been added to the Campaign entity to manage these adjustments.\n\nJan 4, 2026\nEnhanced Publisher and Section Exclusion Experience\n\nWe are introducing a new publisher and section exclusion experience that allows advertisers to apply temporary or permanent blocks, either individually or in bulk. This update provides clearer visibility, predictable behavior, and the ability to easily undo or adjust exclusions via the API.\n\nWhy This Matters\nPublisher traffic can spike temporarily due to breaking news or viral events, attracting audiences that may not align with advertiser intent. During these periods, campaigns often generate clicks with few conversions, inflating costs.\n\nTemporary exclusions allow you to pause this inventory while the news cycle is active. The system then automatically reintroduces the inventory once traffic normalizes—avoiding the need for unnecessary permanent blocks.\n\nTechnical Implementation: New expiration Field under blockedSites\nTo enable temporary blocking, we have added a new optional field named expiration to both the blockedPublishers and blockedSections objects under blockedSites.\n\nKey Functionalities\n\n- \nAuto-Expiration: Temporary exclusions automatically expire and reintroduce inventory without alerts.\n\n- \nRe-activation: You can now update settings for sections that were previously Permanently blocked, overriding the original exclusion state.\n\n- \nInheritance: Duplicated campaigns will inherit the existing exclusion states (Temporary or Permanent) of the original campaign.\n\nImportant Notes\n\n- \nReporting: History changes will now track the distinction between permanent and temporary exclusions.\n\n- \nCSV Limitation: Exclusions uploaded via CSV files remain Permanent by default at this time (the expiration field is not yet supported in CSV uploads).\n\nAction Required\nReview your current blocking logic. If you wish to utilize temporary blocking for viral events, update your integration to populate the expiration field in your blockedPublishers and blockedSections payloads.\n\nOct 16, 2025\nUpcoming Change to Minimum Campaign Budget Effective November 3rd 2025\n\nTo help increase campaign performance and ensure new campaigns can generate results in a timely fashion, we are adjusting the minimum required budget. This change will ensure campaigns have sufficient daily spend for our optimization systems to function effectively\n\nSummary of the Change\n\n- \nWhat: The minimum daily budget for a new campaign will be increased from $20.00 to $25.00 USD.\n\n- \nEffective Date: This change will take effect on November 3rd 2025\n\n- \nScope: This change applies only to newly created campaigns. Existing campaigns with budgets under $25.00 will continue to run without any interruption or required changes.\n\nHow This Affects You\nStarting November 3rd, 2025, any API call to the POST /budgets endpoint will enforce the following rules:\n\n- \nIf type = \"DAILY\", then amount must be greater than or equal to 25.\n\n- \nIf type = \"MONTHLY\", then amount must be greater than or equal to 750.\n\n- \nIf type = \"CAMPAIGN\", then amount must be greater than or equal to 25 x number of campaign days.\n\nAdditionally:\n\n- Any API call to the PUT /budgets endpoint to update campaigns created after November 3rd, 2025, will have the same enforcement rules outlined above.\n\nImportant Note:\nDaily limits for other currencies are exposed via the GET /currencies endpoint.\n\nAction Required\nPlease review your budget and campaign creation and update logic and ensure that any new campaigns are created with a daily budget of at least $25.00. We recommend making this update in your integration before the effective date to ensure a smooth transition.\n\nJul 8, 2025\nNew Performance Report Endpoint - Marketers Report\n\nYou can now retrieve performance reporting aggregated by Marketers aggregation, using your primary account ID.\n\nTo obtain your primary account ID, use the Marketer Entity with the extraFields=Account param.\n\nDec 22, 2024\nNew Filter Added to reporting endpoints: enabledCampaignsOnly\n\nYou can now filter data to include only active campaigns by using the enabledCampaignsOnly field when using our reporting endpoints (promoted content, Periodic, publishers, sections etc).\n\n- \nCurrent Default Value: false\n\n- \nFuture Default Value: true (effective end of January 2025)\n\nPlease note that while the current default value for en"
contact:
name: Outbrain Developer Center
url: https://developer.outbrain.com
servers:
- url: https://api.outbrain.com/amplify/v0.1
description: Production Server
security:
- OBTokenAuth: []
tags:
- name: Performance Reporting
description: 'There are a multitude of reporting endpoints that allow you to retrieve metrics at various levels of granularity.
Note: All performance reports have a 10-30 minutes delay, therefore performance metrics that include the current day are partial.
Rate Limits
Each marketer is limited to 30 requests per minute for the entire performance reporting API. In case of rate limit violation the response status will be 429 (Too Many Requests).
As of April 12, 2021 performance reporting is limited to a history of 3 years per data request.
Response structure
All reporting endpoints share a common response structure, defined below:
Property
Type
Semantic
Comments
results
Array
Metadata and Metrics of the entities returned.
Metadata is an object containing contextual properties of the report entity. The set of properties is specific for each end-point.
totalResults
Number
Count of the total results'
paths:
/reports/fullDay:
get:
operationId: getReportsFullDay
summary: Retrieve last day of full data
description: 'Return the last day for which the data in perfromance reports is complete. Result fields:
Property
Type
Semantic
fullDayDate
Date
Date of the last day with full performance data.
modificationTime
Time
Modification time of the last day of full data.'
tags:
- Performance Reporting
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
example:
fullDayDate: '2019-07-27'
modificationTime: '2019-07-28 02:55:04'
headers:
AMPLIFY-REQUEST-ID:
description: Request correlation / rate-limit signal
schema:
type: string
'400':
description: Bad Request - the request could not be understood or was missing required parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - authentication failed or the user lacks permission for the requested operation
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden - access denied
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found - resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too Many Requests - request exceeded rate limits; see the rate-limit-msec-left header
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/reports/dataFreshness:
get:
operationId: getReportsDataFreshness
summary: Retrieve data freshness
description: 'Return the last timestamps for which the data in performance reports is available. Result fields:
Property
Type
Semantic
finalDataDate
Time
The last timestamp for which the data is complete, usually 0.5 - 1 hour delay.
realTimeDataDate
Time
The last timestamp for which the data is in realtime and not yet finalized, usually 10-20 minutes delay.'
tags:
- Performance Reporting
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
example:
finalDataDate: '2023-07-09 00:00:00'
realTimeDataDate: '2023-07-09 02:45:00'
headers:
AMPLIFY-REQUEST-ID:
description: Request correlation / rate-limit signal
schema:
type: string
'400':
description: Bad Request - the request could not be understood or was missing required parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - authentication failed or the user lacks permission for the requested operation
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden - access denied
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found - resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too Many Requests - request exceeded rate limits; see the rate-limit-msec-left header
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/reports/accounts/{primaryAccountId}/marketers:
get:
operationId: getReportsAccountsPrimaryAccountIdMarketers
summary: Retrieve marketers with performance statistics for a Primary Account
description: 'The API in this sub-section allows retrieving primary account marketers data with performance statistics.
Result fields
Metrics in metrics, metadata in a metadata object containing the following fields:
Property
Type
Semantic
id
String
Marketer ID.
name
String
Marketer name.
status
String
The marketer''s delivery status: ACTIVE, DISABLED, INACTIVE (no spent in the last 30 days), PARTIALLY_ACTIVE (inactive campaign on air status)'
tags:
- Performance Reporting
parameters:
- name: primaryAccountId
in: path
required: true
schema:
type: string
description: Primary Account id. account.salesForceAccountId from Marketer Entity.
example: abf4b02153ee75f3cadc4fc128ab0419ab
- name: from
in: query
required: true
schema:
type: string
description: Start day Date
example: '2015-12-22'
- name: to
in: query
required: true
schema:
type: string
description: End day Date
example: '2016-01-20'
- name: limit
in: query
required: false
schema:
type: number
description: Number of results to return in this request. Used with offset for pagination. default is 10.
example: '10'
- name: offset
in: query
required: false
schema:
type: number
description: Result number to start this response at. zero based. Used with limit for pagination. default is 0.
example: '3'
- name: sort
in: query
required: false
schema:
type: string
description: Can have one of the following values impressions, clicks, ctr, spend, ecpc, conversions, conversionRate, cpa, name, enabled, creativeFormat, budgetStartDate, budgetEndDate and budgetAmount . For more details about reports filtering read this.
example: -ctr
- name: filter
in: query
required: false
schema:
type: string
description: Can have the following values impressions, clicks, ctr, spend, ecpc, conversions, conversionRate, cpa, name, enabled, creativeFormat, budgetStartDate, budgetEndDate, budgetAmount, budgetType, budgetShared and pacingType. For more details about reports filtering read this.
example: clicks+gt+99
- name: conversionsByClickDate
in: query
required: false
schema:
type: boolean
description: Report conversion metrics by click or conversion date, default false (report by conversion date).
example: 'true'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
example:
results:
- metadata:
id: mock-id-0001
name: Mock Marketer Alpha
identifier: '11111111'
status: ACTIVE
metrics:
impressions: 227635064
clicks: 417487
totalConversions: 0
conversions: 0
viewConversions: 0
spend: 165958.65
ecpc: 0.398
ctr: 0.18
dstFeeCost: 0
cpm: 0.73
conversionRate: 0
viewConversionRate: 0
cpa: 0
totalCpa: 0
totalSumValue: 0
sumValue: 0
viewSumValue: 0
totalAverageValue: 0
averageValue: 0
viewAverageValue: 0
totalRoas: 0
roas: 0
videoReachedFirstQ: 0
videoReachedSecondQ: 0
videoReachedThirdQ: 0
videoReachedCompletion: 0
videoViewDuration: 0
videoAvgViewDuration: 0
videoPlays: 0
clicksOnVideo: 0
videoActiveCompletions: 0
videoActiveCompletionsPercentage: 0
appleSKAdNetworkConversions: 0
appleSKAdNetworkRedownload0: 0
appleSKAdNetworkRedownload1: 0
appleSKAdNetworkConversionValue: 0
appleSKAdNetworkConversionAverageValue: 0
- metadata:
id: mock-id-0002
name: Mock Marketer Beta
identifier: '22222222'
status: INACTIVE
metrics:
impressions: 16368480
clicks: 23389
totalConversions: 0
conversions: 0
viewConversions: 0
spend: 8591.07
ecpc: 0.367
ctr: 0.14
dstFeeCost: 0
cpm: 0.52
conversionRate: 0
viewConversionRate: 0
cpa: 0
totalCpa: 0
totalSumValue: 0
sumValue: 0
viewSumValue: 0
totalAverageValue: 0
averageValue: 0
viewAverageValue: 0
totalRoas: 0
roas: 0
videoReachedFirstQ: 0
videoReachedSecondQ: 0
videoReachedThirdQ: 0
videoReachedCompletion: 0
videoViewDuration: 0
videoAvgViewDuration: 0
videoPlays: 0
clicksOnVideo: 0
videoActiveCompletions: 0
videoActiveCompletionsPercentage: 0
appleSKAdNetworkConversions: 0
appleSKAdNetworkRedownload0: 0
appleSKAdNetworkRedownload1: 0
appleSKAdNetworkConversionValue: 0
appleSKAdNetworkConversionAverageValue: 0
- metadata:
id: mock-id-0003
name: Mock Marketer Gamma
identifier: '33333333'
status: INACTIVE
metrics:
impressions: 0
clicks: 0
totalConversions: 0
conversions: 0
viewConversions: 0
spend: 0
ecpc: 0
ctr: 0
dstFeeCost: 0
cpm: 0
conversionRate: 0
viewConversionRate: 0
cpa: 0
totalCpa: 0
totalSumValue: 0
sumValue: 0
viewSumValue: 0
totalAverageValue: 0
averageValue: 0
viewAverageValue: 0
totalRoas: 0
roas: 0
videoReachedFirstQ: 0
videoReachedSecondQ: 0
videoReachedThirdQ: 0
videoReachedCompletion: 0
videoViewDuration: 0
videoAvgViewDuration: 0
videoPlays: 0
clicksOnVideo: 0
videoActiveCompletions: 0
videoActiveCompletionsPercentage: 0
appleSKAdNetworkConversions: 0
appleSKAdNetworkRedownload0: 0
appleSKAdNetworkRedownload1: 0
appleSKAdNetworkConversionValue: 0
appleSKAdNetworkConversionAverageValue: 0
totalResults: 3
summary:
impressions: 244003544
clicks: 440876
totalConversions: 0
conversions: 0
viewConversions: 0
spend: 174549.72
ecpc: 0.396
ctr: 0.18
dstFeeCost: 0
cpm: 0.72
conversionRate: 0
viewConversionRate: 0
cpa: 0
totalCpa: 0
totalSumValue: 0
sumValue: 0
viewSumValue: 0
totalAverageValue: 0
averageValue: 0
viewAverageValue: 0
totalRoas: 0
roas: 0
videoReachedFirstQ: 0
videoReachedSecondQ: 0
videoReachedThirdQ: 0
videoReachedCompletion: 0
videoViewDuration: 0
videoAvgViewDuration: 0
videoPlays: 0
clicksOnVideo: 0
videoActiveCompletions: 0
videoActiveCompletionsPercentage: 0
appleSKAdNetworkConversions: 0
appleSKAdNetworkRedownload0: 0
appleSKAdNetworkRedownload1: 0
appleSKAdNetworkConversionValue: 0
appleSKAdNetworkConversionAverageValue: 0
headers:
AMPLIFY-REQUEST-ID:
description: Request correlation / rate-limit signal
schema:
type: string
'400':
description: Bad Request - the request could not be understood or was missing required parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - authentication failed or the user lacks permission for the requested operation
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: Forbidden - access denied
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Not Found - resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: Too Many Requests - request exceeded rate limits; see the rate-limit-msec-left header
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/reports/marketers/{id}/campaigns:
get:
operationId: getReportsMarketersIdCampaigns
summary: Retrieve campaigns with performance statistics for a Marketer
description: 'The API in this sub-section allows retrieving marketer campaigns data with performance statistics.
Result fields
Metrics in metrics, metadata in a metadata object containing the following fields:
Property
Type
Semantic
id
String
Campaign ID.
name
String
Campaign name.
campaignOnAir
Boolean
Is the campaign on air, same as campaignOnAir in Live Status.
onAirReason
Campaign On Air Reason
The reason for the campaign on air status, same as onAirReason in Live Status.
enabled
Boolean
Is the campaign enabled.
budget
Budget
Partial Budget entity of a campaign. For full details use Budget.
lastCappingTime
Time
Optional. Latest date and time the campaign was capped for selected date range. Data is available for up to 30 days ago.
cpc
Money
Cost per monetized user action (for example cost per click). See Currencies for valid cost values.
creativeFormat
Campaign creative format
The campaign creative format.'
tags:
- Performance Reporting
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Marketer id
example: abf4b02153ee75f3cadc4fc128ab0419ab
- name: from
in: query
required: true
schema:
type: string
description: Start day Date
example: '2015-12-22'
- name: to
in: query
required: true
schema:
type: string
description: End day Date
example: '2016-01-20'
- name: limit
in: query
required: false
schema:
type: number
description: Number of results to return in this request. Used with offset for pagination. default is 10.
example: '10'
- name: offset
in: query
required: false
schema:
type: number
description: Result number to start this response at. zero based. Used with limit for pagination. default is 0.
example: '3'
- name: sort
in: query
required: false
schema:
type: string
description: Can have one of the following values impressions, clicks, ctr, spend, ecpc, conversions, conversionRate, cpa, name, enabled, creativeFormat, budgetStartDate, budgetEndDate and budgetAmount . For more details about reports filtering read this.
example: -ctr
- name: filter
in: query
required: false
schema:
type: string
description: Can have the following values impressions, clicks, ctr, spend, ecpc, conversions, conversionRate, cpa, name, enabled, creativeFormat, budgetStartDate, budgetEndDate, budgetAmount, budgetType, budgetShared and pacingType. For more details about reports filtering read this.
example: clicks+gt+99
- name: includeArchivedCampaigns
in: query
required: false
schema:
type: boolean
description: Include data of archived campaigns, default false.
example: 'true'
- name: budgetId
in: query
required: false
schema:
type: string
description: Limit to data of the budget with the given ID.
example: adc4fc128ab0419ababf4b02153ee75f3c
- name: campaignId
in: query
required: false
schema:
type: string
description: Limit to data of the campaign with the given IDs (takes precedence over budgetId).
example: e75f3cadc4fc128ab0419ababf4b02153e, 0069fc0fe9598f99b4c528f0881cd74b4b
- name: includeConversionDetails
in: query
required: false
schema:
type: boolean
description: Include metrics of conversion pixels, default false.
example: 'true'
- name: conversionsByClickDate
in: query
required: false
schema:
type: boolean
description: Report conversion metrics by click or conversion date, default false (report by conversion date).
example: 'true'
- name: includeViewedImpressions
in: query
required: false
schema:
type: boolean
description: When true, includes viewableImpressions in the response metrics. Default false.
example: 'false'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
example:
results:
- metadata:
id: 00f4b02153ee75f3c9dc4fc128ab041962
name: Boost 'ABC' Brand
campaignOnAir: false
onAirReason: CAMPAIGN_DISABLED
enabled: false
budget:
id: 00a6bf53c0e7231db16501ea78e750d16f
shared: false
amount: 2500
currency: USD
startDate: '2015-05-23'
endDate: ''
type: DAILY
pacing: SPEND_ASAP
cpc: 0.081
lastCappingTime: '2015-05-24 21:56:22'
creativeFormat: Standard
metrics:
impressions: 4969401
clicks: 2061
totalConversions: 6
conversions: 5
viewConversions: 1
spend: 1532.44
ecpc: 0.74
ctr: 0.04
conversionRate: 0.24
viewConversionRate: 0
cpa: 306.49
totalCpa: 255.41
totalValue: 243.31
totalSumValue: 294.66
sumValue: 243.31
viewSumValue: 51.35
totalAverageValue: 49.11
averageValue: 48.66
viewAverageValue: 51.35
roas: 0.8
totalRoas: 0.6
conversionMetrics:
- name: Purchase
totalConversions: 1
conversions: 1
viewConversions: 0
conversionRate: 0.05
viewConversionRate: 0
totalCpa: 1532.44
cpa: 1532.44
totalValue: 240
totalSumValue: 240
sumValue: 240
viewSumValue: 0
totalAverageValue: 240
averageValue: 240
viewAverageValue: 0
roas: 0.3
totalRoas: 0.3
- name: View
totalConversions: 102
conversions: 99
viewConversions: 3
conversionRate: 4.8
viewConversionRate: 0
totalCpa: 15.02
cpa: 15.48
totalValue: 0
totalSumValue: 0
sumValue: 0
viewSumValue: 0
totalAverageValue: 0
averageValue: 0
viewAverageValue: 0
roas: 0
totalRoas: 0
- name: Add To Cart
totalConversions: 6
conversions: 5
viewConversions: 1
conversionRate: 0.24
viewConversionRate: 0
totalCpa: 255.41
cpa: 306.49
totalValue: 243.31
totalSumValue: 294.66
sumValue: 243.31
viewSumValue: 51.35
totalAverageValue: 49.11
averageValue: 48.66
viewAverageValue: 51.35
roas: 0.8
totalRoas: 0.7
totalResults: 19
summary:
impressions: 15615028
clicks: 10756
totalConversions: 18
conversions: 17
viewConversions: 1
spend: 5693.03
ecpc: 0.53
ctr: 0.07
conversionRate: 0.16
viewConversionRate: 0
cpa: 334.88
totalCpa: 316.28
totalValue: 1099.6
totalSumValue: 1150.95
sumValue: 1099.6
viewSumValue: 51.35
totalAverageValue: 63.94
averageValue: 64.68
viewAverageValue: 51.35
roas: 0.8
totalRoas: 0.6
conversionMetrics:
- name: Add To Cart
totalConversions: 18
conversions: 17
viewConversions: 1
conversionRate: 0.16
viewConversionRate: 0
totalCpa: 316.28
cpa: 334.88
totalValue: 1099.6
totalSumValue: 1150.95
sumValue: 1099.6
viewSumValue: 51.35
totalAverageValue: 63.94
averageValue: 64.68
# --- truncated at 32 KB (341 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/outbrain/refs/heads/main/openapi/outbrain-performance-reporting-api-openapi.yml