Outbrain Developer Center

Date

All date attributes are in 'yyyy-MM-dd' format. E.g. January 11th, 2015 is: 2015-01-26.

Time

All time attributes are in 'yyyy-MM-dd HH:mm:ss' format, where the time is with accordance to ET with 0..23 hour representation. E.g. 2013-02-28 17:43:19.

Hour of Day

All hour of day attributes are in 'HH:00' format. E.g. 4pm is: 16:00 while 4am is: 04:00

Money

Money is a decimal number with precision of 2 digits after the decimal point.

Platform

A platform is one of the following:

DESKTOP - The content was consumed via desktop.
MOBILE - The content was consumed via mobile.
TABLET - The content was consumed via tablet.

Platform Operating System

A platform breakdown operating system can be one of the following:

Ios - The content was consumed via Ios.
MacOs - The content was consumed via MacOs.
Android - The content was consumed via Android.
Windows - The content was consumed via Windows.
Other - The content was consumed via Other operating system.

Platform Browser

A platform breakdown browser can be one of the following:

Chrome - The content was consumed via Chrome browser.
Firefox - The content was consumed via Firefox browser.
Safari - The content was consumed via Safari browser.
InternetExplorer - The content was consumed via InternetExplorer browser.
Opera - The content was consumed via Opera browser.
Samsung - The content was consumed via Samsung browser.
UCBrowser - The content was consumed via UCBrowser.
InApp - The content was consumed via InApp browser.
Edge - The content was consumed via Edge browser. Data only available as separate from Internet explorer starting on July 13th, 2020.
Other - The content was consumed via Other browser.

Review Status

A PromotedLink review status is one of the following:

APPROVED - PromotedLink content is approved
PENDING - PromotedLink content is in the proccess of being reviewed
REJECTED - PromotedLink content is rejected

Approval Review Status

A PromotedLink approval status is one of the following:

Approved - PromotedLink content is approved
Pending - PromotedLink content is in the proccess of being reviewed
Rejected - PromotedLink content is rejected

Approval Status

A PromotedLink Approval Status Object has the following attributes:

Property	Type	Semantic
status	ApprovalReviewStatus	The Status of the PromotedLink) read only
reasons	array of String (Optional)	Indicates the reasons only if your content is rejected (ApprovalReviewStatus is `Rejected`) read only
isEditable	Boolean	Indicates if the PromotedLink is able to be edited. `true` if the ApprovalReviewStatus is `Pending`)

OnAir Status

A PromotedLink OnAir Status Object has the following attributes:

Property	Type	Semantic
onAir	Boolean	Indicates whether the PromotedLinks is onAir (can be served) read only
reason	String (Optional)	Indicates a meaningful reason in case the onAir property is false read only

Campaign On Air Reason

A Campaign on air reason is one of the following:

CAMPAIGN_ON_AIR
CAMPAIGN_DISABLED - Your campaign is Paused. Switch to play to run it.
CAMPAIGN_FLY_DATES_PAST - Your campaign has ended.
CAMPAIGN_FLY_DATES_FUTURE - Your campaign is scheduled to start on a future date.
CAMPAIGN_DAILY_CAPPED - Your daily budget has been reached and will resume tomorrow. To increase running time, edit budget settings.
CAMPAIGN_DAILY_CAPPED_MONTHLY - Your budget for the day has been reached. Your campaign will resume tomorrow, and has used <CURRENCY_SYMBOL><spentAmount> of its monthly budget.
CAMPAIGN_DAILY_CAPPED_CAMPAIGN - Your budget for the day has been reached. Your campaign will resume tomorrow, and has used <CURRENCY_SYMBOL><spentAmount> of its budget.
CAMPAIGN_BUDGET_DEPLETED - Your campaign has reached its monthly budget limit, and will resume on the first day of next month.
CAMPAIGN_ALL_PROMOTED_LINKS_DISABLED - Your content is not enabled.
CAMPAIGN_ALL_PROMOTED_LINKS_REJECTED - Your content has not been approved. View content guidelines.
ALL_PROMOTED_LINKS_EXPIRED - Your content has expired.
ALL_PROMOTED_LINKS_PENDING - Your content is under editorial review.
WAITING_FOR_START_HOUR - Your campaign will resume at its scheduled start time tomorrow.
NO_RUNNING_PROMOTED_LINKS - Your content is not currently running.
MISSING_BILLING_INFO - There is no credit card on file for this account. Please contact us.
EXPIRED_BILLING_INFO - The credit card on file expired. Please contact us.
FAILED_BILLING_INFO - There is a problem with the credit card on file. Please contact us.
BAD_CONTENT - The account is blocked. For more details please contact us.
OUTSTANDING_UNPAID_BALANCE - There is outstanding balance on the account. Please contact us.
TOS_VIOLATION - There is a problem with the account. Please contact us.
NEW_CUSTOMER_PENDING - Your content is under review. Please contact uswith any questions.
PAUSED - There is a problem with the account. Please contact us.
MARKED_DELETED - This account is no longer active. To resume please contact us.
LEGACY_UNKNOWN - There is a problem with the account. Please contact us.
FAILED_THRESHOLD_BILLING - There is a problem with the credit card on file. Please contact us.
CAMPAIGN_NOT_IN_SCHEDULING_HOURS - Your campaign will resume according to it's scheduling configuration.
ALL_DOCUMENTS_UNAVAILABLE - All of your campaign content links currently cannot be reached.

Call To Action

A PromotedLink Call To Action Object has the following attributes:

Property	Type	Semantic
type	Call To Action Type	Indicates call to action type on promoted link
value	String	Call to action type translation read only

Call To Action Type

Call to action type is one of the following:

NONE
APPLY_NOW
BOOK_NOW
CONTACT_US
DOWNLOAD
LEARN_MORE
GET_QUOTE
SHOP_NOW
SIGN_UP
WATCH_MORE
LISTEN_NOW
SUBSCRIBE
RSVP
REGISTER_NOW
INSTALL_APP
READ_MORE
PLAY_GAME
DONATE_NOW

Property	Type	Semantic
id	String	Unique image identifier. On input, use instead of url to reuse an already-uploaded image. (optional)
url	String	On input, an http link to the image to use, no separate upload needed. (input only, optional)
requestedImageUrl	String	The image url with the requested dimensions. (output only)
originalImageUrl	String	The image url with the original dimensions. output only. optional
thumbnailUrl	String	The image thumbnail url for MP4/GIF image type. output only
playMode	Play Mode type	The image play mode type (relevant to MP4 and GIF image types) - Determines whether the clip would run once or loop 3 times.
stream	String	The image content in bytes. input only. optional
type	Image type	The image type. output only
cropSettings	array of Crop Point	The image custom crop settings. can be sent only for Standard images. optional
cropType	Crop Type	The image’s custom crop type. (optional)
aiGenerated	Boolean	Whether this creative was fully or partially generated or modified by an AI tool. When `true`, Outbrain embeds a compliant AI watermark with correctly encoded C2PA metadata before delivery. When `false` or omitted, you confirm the creative is either non-AI, or already carries compliant AI watermarks and metadata — in which case Outbrain preserves them as supplied and you retain responsibility for their accuracy. Accurate declaration is required under EU AI Act Article 50(4), applicable from 2 August 2026. False or missing declarations may result in creative rejection, account suspension, and regulatory penalties.

Property	Type	Semantic
url	String	The logo image url. Typically the only field you need, Outbrain fetches and stores the image for you. (optional)
id	String	Logo id, echoed back on output. Rarely needed on input, only to re-apply a previously-returned logo. (optional)

Play Mode Type

An Image Play Mode type is one of the following:

Once
Loop

Image Type

An Image type is one of the following:

Standard
GIF
MP4

Crop Point

A Crop Point consist from:

Property	Type	Semantic
ratio	Ratio type	Image Ratio
x	Integer	Image top left x coordinate
y	Integer	Image top left y coordinate
w	Integer	Image custom width
h	Integer	Image custom height

Crop Point Ratio Type

A Ratio type is one of the following:

1:1
4:3
3:2
8:5
16:9
1.91:1

Crop Type

An Image Crop type is one of the following:

Fill
Blur
DominantColor

Budget Type

A Budget type is one of the following:

CAMPAIGN - The budget is one-time and does not repeat
MONTHLY - The budget repeats per month
DAILY - The budget repeats per day

Pacing Type

A pacing type is one of the following:

SPEND_ASAP - The budget should be spent ASAP, with no daily capping
AUTOMATIC - Allow the Outbrain engine to decide on the budget spend pacing
DAILY_TARGET - The budget should be spent on a daily basis, with a limit at this target amount

Campaign Optimization Type

Represents the type of the campaign optimization.

TRAFFIC - Campaign optimized towards maximizing traffic (clicks)
CPC - Campaign optimized towards bringing traffic to the highest converting sections using automatic CPC adjustment per serving
MAX_CONVERSION_FULLY_AUTOMATED - Campaign optimized towards maximizing the number of conversions within your budget. Note: this mode might change your campaign’s CPC.
TARGET_CPA_FULLY_AUTOMATED - Campaign optimized towards a target CPA for a specific conversion event. Note: this mode might change your campaign’s CPC.
TARGET_ROAS_FULLY_AUTOMATED - Campaign optimized towards a target ROAS for a specific conversion event. Note: this mode might change your campaign’s CPC. Click here to learn more about target ROAS.

Max Daily Average CPC Recommendation

In case your CBS automatic campaign can not increase the CPC (and the algorithm recommends to increase it), follow these recommendations

INCREASE_BID_CAP - Increase the value of automaticModeMaxAvgDailyCpc (or for old campaigns - automaticModeMaxCpc)
INCREASE_TARGET_CPA - There is no automaticModeMaxAvgDailyCpc, but your target CPA is lower than the desired CPC. Increase the target CPA
NO_RECOMMENDATION_INTERNAL_ERROR - an error occured during recommendation calculation
NO_RECOMMENDATION_MAX_CURRENCY - there is no recommendation

Volume Control Adjustment Level

Represents the desired volume adjustment for a section.

INCREASE - Significantly increase traffic from the section.
SLIGHTLY_INCREASE - Slightly increase traffic from the section.
SLIGHTLY_DECREASE - Slightly decrease traffic from the section.

Campaign On Air Type

Represents the scheduling type for the campaign to be on air.

Scheduled - Campaign will be on air based on it's Scheduling Rules.
StartHour - Campaign will be on air based on it's StartHour property.

Day Of Week

Sunday
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday

Content Type

A content type is one of the following:

ARTICLES - The content of this campaign is articles
NATIVE_VIDEO - The content of this campaign is video

Segment Type

A segment type is one of the following:

PIXEL - This segment type includes users who visited a specific page on your site (membership defined by a set of pixel rules)
CLICKERS - This segment type includes users who clicked on a specific campaign (membership defined by a list of clicker campaigns)
DMP - This segment type includes the users from your specific DMP segment.
LOOK_A_LIKES - This segment type includes similar users from your seed segment. You can create lookalike based of the following segment types: CLICKERS, PIXEL and DMP.
CONVERSION - This segment type includes users which are candidates for conversion.
VALUABLE_CONVERSION - This segment type includes users that triggered a conversion that is worth a defined value (based on the defined rule).

Pixel Rule Type

A pixel rule type is one of the following:

UrlStartsWith - The rule enforces a match on the url prefix
UrlDoesNotStartWith - The rule enforces a lack of match on the url prefix
UrlEndsWith - The rule enforces a match the url suffix
UrlDoesNotEndWith - The rule enforces a lack of match the url suffix
UrlContains - The rule enforces a match on a substring of the url
UrlDoesNotContain - The rule enforces a lack of match on a substring of the url
UrlEquals - The rule enforces a match to the entire url
UrlDoesNotEqual - The rule enforces a lack of match on the url prefix

Value Based Converters Rule Type

A Value Based Converters rule type is one of the following:

EqualsTo - The rule enforces a match on the value of conversion
GreaterThanEqual - The rule enforces a match or a greater number on the value of converesion
LowerThan - The rule enforces a lower number on the value of the conversion
BetweenInclusive - The rule enforces an inclusive range on the value of the conversion

A tracking status is one of the following. The status will be "inactive" until the first user has been added to the cookie pool, once a user has been added the status will be “active” indicating the pixel is firing and collecting new users.

ACTIVE - The tracking status is active
INACTIVE - The tracking status is inactive

Block status

The blocking status of a publisher or section. Can be one of the following:

Unblocked - No blocking at any level
Blocked - Fully blocked at all levels
PartialBlock - Blocking on some levels

Block types

A map of block types to Boolean values, describing the blocking status (true for blocked, false for non-blocked) of a publisher or section in context of entire marketer or specific campaign. Map key values:

marketerPublisher
marketerSection
campaignPublisher
campaignSection
oenOptOut (Planned removal October 18th)

Conversion Event Category

Represents the category of the Conversion Event.

CHECKOUT
REGISTRATION
EMAIL_SIGN_UP
VIDEO_VIEW
LEAD
ADD_TO_CART
CONTENT_VIEW
DOWNLOAD
OTHER
SEARCH
PURCHASE
TIME_ON_PAGE (relevant to engagement conversions only)
MOUSE_CLICK (relevant to engagement conversions only)
SCROLL_DEPTH (relevant to engagement conversions only)

Conversion Event Type

Represents the type of the Conversion Event.

URL_BASED
EVENT_BASED
ENGAGEMENT

Conversion Event Segment

A Conversion Event Segment Object has the following attributes:

Property	Type	Semantic
id	String	The id of the segment read only
name	String	The name of the segment read only
enabled	boolean	The segment enabled status read only

Prefix Tracking Code

A Prefix Tracking Code Object has the following attributes:

Property	Type	Semantic	Example	Semantic
prefix	String	The marketer's prefix url	"http://www.marketersServer.com?redirectTo="
encode	boolean	Whether to encode the PromotedLink followed by the prefix or not	false	true by default.

The prefix property can't contain dynamic parameters.

Suffix Tracking Code

A Suffix Tracking Code is a parameter list that will be appended to the Campaign's PromotedLink. Use the value "EMPTY_SUFFIX" to delete.

A Suffix Tracking Code Object can also contain the following Dynamic Parameters:

promoted_link_id - The id of the promoted link
campaign_id - The id of the campaign
section_id - Referring section ID
section_name - Referring section name
source_id - (deprecated - should use section_id instead)
publisher_id - Referring publisher ID
publisher_name - Referring publisher name
ob_click_id - Oubtrain click id

Geo Location Type

A GeoLocation type can be one of the following:

Country - A GeoLocation representation of a country
Region - A GeoLocation representation of a region
SubRegion - A GeoLocation representation of a subregion
DMA - A GeoLocation representation of a DMA
PostalCode - A GeoLocation representation of a postal code

Tracking Pixel

A tracking pixel is the url that will be called once a promoted link with this pixel is clicked.

Parameter options:

uuid - user id
cid - campaign Id
pc_id - promoted link id
did - document Id
aid - marketer Id
doc_title - document title
ad_title - promoted link title
time_stamp - the time this pixel was fired
campaign_id - campaign id
section_name - section name
cpc - cost per click
referral_url - referral url
gdpr_pd - is containing personal data
gdpr - is from gdpr country
gdpr_consent - consent string
campaign_name - campaign name
ad_id - ad id
ad_name - ad name
doc_id - document Id
publisher_id - publisher id
publisher_name - publisher name
req_id - request id
section_id - section id
promoted_link_id - promoted link id
local_cpc - local cpc
promoted_link_sequence_id - promoted link sequence id

Pixels

A pixels object consists from impression and tracking pixels. Please use CampaignPixels extraField.

Property	Type	Semantic
impressionPixels	Array of String	Impression pixel is the url that will be called once a promoted link with this pixel is viewed.
trackingPixels	Array of String	Tracking pixel is the url that will be called once a promoted link with this pixel is clicked.
acceptResponsibility	Boolean	Accepting responsibility for new pixels. Mandatory. Please note that the customer is solely responsible for costs related to any third party fees incurred by customer or on behalf of customer for implementing any click or impression tracker on customer’s campaign(s). Customer may only implement click or impression trackers if (i) it has provided appropriate notice to users regarding use; (ii) honours end-user consent signals; and (iii) complies with applicable laws.

Dynamic Parameters

A Dynamic Parameter is one that its value gets populated at serving time.

When using a dynamic parameter, one must wrap the parameter name by double curly braces.

Usage examples:

In Prefix Tracking Code: http://www.marketersServer.com?sectionId={{section_id}}
In Suffix Tracking Code: promotedLink={{promoted_link_id}}

Block status

The blocking status of a publisher or section. Can be one of the following:

Unblocked - No blocking at any level
Blocked - Fully blocked at all levels
PartialBlock - Blocking on some levels

Block types

marketerPublisher
marketerSection
campaignPublisher
campaignSection

Tracking Status

Indicates if the Conversion Event is Active or Inactive.

ACTIVE
INACTIVE

Conversion Event Type

Represents the type of the Conversion Event.

URL_BASED
EVENT_BASED

Sort Field

Sort the results by one of the metric columns with -/+ to indicate descending/ascending sorts. Only one sort is possible per request.

Publisher Type

The type of the publisher. Can be one of the following:

ExtendedNetwork - A premium publisher site beyond Outbrain’s direct placements

Section Type

The type of the section. Can be one of the following:

ExtendedNetwork - A section of a premium publisher site beyond Outbrain’s direct placements

Sub Segment Status

Represents the status of the Lookalike sub segment. Can be one of the following:

IN_PROGRESS - The Lookalike sub segment is now being modeled. You can target it to a campaign and the segment will automatically apply when it is ready.
ACTIVE - The Lookalike sub segment is active

Lookalike Segment Status

Aggregative status of the model of the Lookalike segment based on the statuses of its subsegments. Can be one of the following:

IN_PROGRESS - All subsegments are currently being modeled
ACTIVE - All subsegments are active
DISABLED - The Lookalike segment is disabled
INACTIVE - No subsegment was targeted in the last month
PARTIALLY_READY - At least one of the subsegments is currently being modeled

Affinity

Represents how much your audience is homogeneous, the more homogeneous the better the Lookalike model that is created.

LOW
MEDIUM
HIGH

Provider

Represents the supported DMP providers. Can be one of the following:

LiveRamp
BlueKai
Adobe
IntimateMerger

Campaign Objective

Represents the campaign objective. Can be one of the following:

Awareness - Supported Optimization Types: TRAFFIC
Traffic - Supported Optimization Types: TRAFFIC
Conversions - Supported Optimization Types: CPC, MAX_CONVERSION_FULLY_AUTOMATED, TARGET_CPA_FULLY_AUTOMATED and TARGET_ROAS_FULLY_AUTOMATED
AppInstalls - Supported Optimization Types: CPC, MAX_CONVERSION_FULLY_AUTOMATED, TARGET_CPA_FULLY_AUTOMATED and TARGET_ROAS_FULLY_AUTOMATED

Campaign Creative Format

Represents the campaign creative format. Can be one of the following:

Standard
AppInstall
Carousel
Clip

Feed Status

Represents the status of the Dynamic Retargeting feed. Can be one of the following:

Pending - The feed hasn't been loaded yet
InProgress - The feed is being loaded
Ready - The load has completed successfully
ImportFailure - The load has failed on downloading the feed
InvalidFormatFailure - The load has failed since the feed format is invalid
Failure - The load has failed

User Role

Represents the group of permissions a user has for a marketer. Can be one of the following:

OWNER - The owner of the marketer. It has all permissions. Only a single user can have the OWNER role
ADMIN - ADMIN user has the same permissions as the OWNER except that ADMIN can't change the OWNER
CAMPAIGN_MANAGER - CAMPAIGN_MANAGER is allowed to edit campaigns only
VIEWER - VIEWER is allowed to view campaigns only

Reference Types

On this page