Brist API Reference
Welcome to the Brist GraphQL API!
Terms of Service
API Endpoints
# Production:
https://api.brist.ai/api/query
Headers
# Get your API key on your dashboard at https://app.brist.ai/api_keys.
Authorization: Bearer <YOUR_TOKEN_HERE>
Queries
adAccountAdStats
Description
Get the advertising statistics (clicks, impressions, cost) for a given advertiser on your marketplace.
Response
Returns
[AdStat!]
Arguments
Name | Description |
---|---|
accountId -
Int!
|
The ID of the ad account you want statistics for. This must be an account managed by your marketplace. |
range -
TimeRange!
|
The date range you want statistics calculated over (day-level resolution). The range is inclusive of both endpoints. |
Example
Query
query adAccountAdStats(
$accountId: Int!,
$range: TimeRange!
) {
adAccountAdStats(
accountId: $accountId,
range: $range
) {
day
clicks
impressions
price
}
}
Variables
{"accountId": 123, "range": TimeRange}
Response
{
"data": {
"adAccountAdStats": [
{
"day": "10:15:30Z",
"clicks": 123,
"impressions": 123,
"price": 123
}
]
}
}
adAccounts
Description
adAccounts
Response
Returns
[AdAccount!]
Example
Query
query adAccounts(
$limit: Int!,
$offset: Int!
) {
adAccounts(
limit: $limit,
offset: $offset
) {
id
name
accountType
createdAt
}
}
Variables
{"limit": 123, "offset": 987}
Response
{
"data": {
"adAccounts": [
{
"id": 987,
"name": "xyz789",
"accountType": "BRIST_MANAGED_ACCOUNT_TYPE",
"createdAt": "10:15:30Z"
}
]
}
}
adUnitAdStats
Description
Get the advertising statistics (clicks, impressions, cost) for a specific ad unit.
Response
Returns
[AdStat!]
Arguments
Name | Description |
---|---|
adUnitId -
Int!
|
The ID of the ad unit you want statistics for. This must be an unit that is managed by an account under your marketplace. |
range -
TimeRange!
|
The date range you want statistics calculated over (day-level resolution). The range is inclusive of both endpoints. |
Example
Query
query adUnitAdStats(
$adUnitId: Int!,
$range: TimeRange!
) {
adUnitAdStats(
adUnitId: $adUnitId,
range: $range
) {
day
clicks
impressions
price
}
}
Variables
{"adUnitId": 987, "range": TimeRange}
Response
{
"data": {
"adUnitAdStats": [
{
"day": "10:15:30Z",
"clicks": 123,
"impressions": 123,
"price": 123
}
]
}
}
marketplaceAdStats
Description
Get the advertising statistics (clicks, impressions, cost) across all advertisers on your marketplace.
Response
Returns
[AdStat!]
Arguments
Name | Description |
---|---|
range -
TimeRange!
|
The date range you want statistics calculated over (day-level resolution). The range is inclusive of both endpoints. |
Example
Query
query marketplaceAdStats($range: TimeRange!) {
marketplaceAdStats(range: $range) {
day
clicks
impressions
price
}
}
Variables
{"range": TimeRange}
Response
{
"data": {
"marketplaceAdStats": [
{
"day": "10:15:30Z",
"clicks": 123,
"impressions": 123,
"price": 123
}
]
}
}
Mutations
createAutobiddingSearchAdUnit
Description
Creates a search unit that uses autobidding (a fixed monthly budget, with optional daily maximums), in order to display ads
Response
Returns an
AdUnit!
Arguments
Name | Description |
---|---|
input -
CreateAutobiddingSearchAdUnitInput!
|
Example
Query
mutation createAutobiddingSearchAdUnit($input: CreateAutobiddingSearchAdUnitInput!) {
createAutobiddingSearchAdUnit(input: $input) {
id
name
productIds
monthlyBudgetCents
unitType
unitData {
... on FixedBidSearchUnitData {
...FixedBidSearchUnitDataFragment
}
... on AutobiddingSearchUnitData {
...AutobiddingSearchUnitDataFragment
}
}
}
}
Variables
{"input": CreateAutobiddingSearchAdUnitInput}
Response
{
"data": {
"createAutobiddingSearchAdUnit": {
"id": 123,
"name": "xyz789",
"productIds": ["xyz789"],
"monthlyBudgetCents": 123,
"unitType": "AUTOBIDDING_SEARCH_UNIT",
"unitData": FixedBidSearchUnitData
}
}
}
createFixedBidSearchAdUnit
Description
Creates a search unit that pays a fixed price for all ad space.
Response
Returns an
AdUnit!
Arguments
Name | Description |
---|---|
input -
CreateFixedSearchAdUnitInput!
|
Example
Query
mutation createFixedBidSearchAdUnit($input: CreateFixedSearchAdUnitInput!) {
createFixedBidSearchAdUnit(input: $input) {
id
name
productIds
monthlyBudgetCents
unitType
unitData {
... on FixedBidSearchUnitData {
...FixedBidSearchUnitDataFragment
}
... on AutobiddingSearchUnitData {
...AutobiddingSearchUnitDataFragment
}
}
}
}
Variables
{"input": CreateFixedSearchAdUnitInput}
Response
{
"data": {
"createFixedBidSearchAdUnit": {
"id": 123,
"name": "xyz789",
"productIds": ["abc123"],
"monthlyBudgetCents": 123,
"unitType": "AUTOBIDDING_SEARCH_UNIT",
"unitData": FixedBidSearchUnitData
}
}
}
createSelfManagedAdAccount
Description
Creates an ad account that has billing managed by you.
Response
Returns an
AdAccount!
Arguments
Name | Description |
---|---|
input -
SelfManagedAdAccountInput!
|
Example
Query
mutation createSelfManagedAdAccount($input: SelfManagedAdAccountInput!) {
createSelfManagedAdAccount(input: $input) {
id
name
accountType
createdAt
}
}
Variables
{"input": SelfManagedAdAccountInput}
Response
{
"data": {
"createSelfManagedAdAccount": {
"id": 123,
"name": "abc123",
"accountType": "BRIST_MANAGED_ACCOUNT_TYPE",
"createdAt": "10:15:30Z"
}
}
}
recordAdClick
Description
Records a click on an ad that was created from an auction.
Response
Returns an
AdData!
Arguments
Name | Description |
---|---|
input -
AdClickEventInput!
|
Example
Query
mutation recordAdClick($input: AdClickEventInput!) {
recordAdClick(input: $input) {
time
auction {
...AuctionFragment
}
productId
marketplaceUserId
dataType
}
}
Variables
{"input": AdClickEventInput}
Response
{
"data": {
"recordAdClick": {
"time": "10:15:30Z",
"auction": Auction,
"productId": "xyz789",
"marketplaceUserId": "xyz789",
"dataType": "IMPRESSION_DATA_TYPE"
}
}
}
recordAdImpressions
Description
Records an impression on an ad that was created from an auction.
Response
Returns
[AdData!]
Arguments
Name | Description |
---|---|
input -
AdImpressionsEventInput!
|
Example
Query
mutation recordAdImpressions($input: AdImpressionsEventInput!) {
recordAdImpressions(input: $input) {
time
auction {
...AuctionFragment
}
productId
marketplaceUserId
dataType
}
}
Variables
{"input": AdImpressionsEventInput}
Response
{
"data": {
"recordAdImpressions": [
{
"time": "10:15:30Z",
"auction": Auction,
"productId": "abc123",
"marketplaceUserId": "xyz789",
"dataType": "IMPRESSION_DATA_TYPE"
}
]
}
}
recordExternalProductClick
Description
Records a click on a product that was shown organically. The data collected will help refine ad targeting.
Response
Returns an
ExternalData!
Arguments
Name | Description |
---|---|
input -
ProductClickInput!
|
Example
Query
mutation recordExternalProductClick($input: ProductClickInput!) {
recordExternalProductClick(input: $input) {
time
productId
marketplaceUserId
dataType
}
}
Variables
{"input": ProductClickInput}
Response
{
"data": {
"recordExternalProductClick": {
"time": "10:15:30Z",
"productId": "xyz789",
"marketplaceUserId": "abc123",
"dataType": "EXTERNAL_CLICK_DATA_TYPE"
}
}
}
runSearchAuction
Description
Runs a search ad auction given a set of candidates.
Response
Returns an
Auction!
Arguments
Name | Description |
---|---|
input -
AuctionInput!
|
Example
Query
mutation runSearchAuction($input: AuctionInput!) {
runSearchAuction(input: $input) {
id
adSlots
candidates {
...AuctionCandidateFragment
}
marketplaceUserId
auctionWinners {
...AuctionWinnerFragment
}
}
}
Variables
{"input": AuctionInput}
Response
{
"data": {
"runSearchAuction": {
"id": 123,
"adSlots": 987,
"candidates": [AuctionCandidate],
"marketplaceUserId": "xyz789",
"auctionWinners": [AuctionWinner]
}
}
}
Types
AdAccount
Fields
Field Name | Description |
---|---|
id -
Int!
|
|
name -
String!
|
|
accountType -
AdAccountType!
|
|
createdAt -
Time!
|
Example
{
"id": 987,
"name": "abc123",
"accountType": "BRIST_MANAGED_ACCOUNT_TYPE",
"createdAt": "10:15:30Z"
}
AdAccountType
Values
Enum Value | Description |
---|---|
|
|
|
Example
"BRIST_MANAGED_ACCOUNT_TYPE"
AdClickEventInput
Fields
Input Field | Description |
---|---|
time -
Time
|
The time that this event occurred. If left blank this defaults to the current time. |
adUnitData -
AdUnitDataInput
|
adUnitData contains the relevant information about the ad unit that was clicked. |
Example
{
"time": "10:15:30Z",
"adUnitData": AdUnitDataInput
}
AdData
Description
AdData represents an event (click/impression/etc.) associated with an ad. When you record a click, cost per click ads are billed to your ad accounts.
Fields
Field Name | Description |
---|---|
time -
Time!
|
The time this event occurred |
auction -
Auction!
|
The auction that this event is associated with |
productId -
String!
|
The marketplace's identifier of the product that the event is associated with. |
marketplaceUserId -
String
|
marketplaceUserId is an an optional identifier for the user that is logged in when browsing the website. If your users are generally not logged in, you can generate an identifier and use persistent storage client-side to identify the user. |
dataType -
AdDataType!
|
The type of data (click/impression). |
Example
{
"time": "10:15:30Z",
"auction": Auction,
"productId": "xyz789",
"marketplaceUserId": "xyz789",
"dataType": "IMPRESSION_DATA_TYPE"
}
AdDataType
Values
Enum Value | Description |
---|---|
|
Represents an impression of an ad |
|
Represents a click of an ad |
Example
"IMPRESSION_DATA_TYPE"
AdImpressionsEventInput
Fields
Input Field | Description |
---|---|
time -
Time
|
The time that this event occurred. If left blank this defaults to the current time. |
impressionData -
[AdUnitDataInput]
|
impressionData contains information about the ad units that were shown to the user. |
Example
{
"time": "10:15:30Z",
"impressionData": [AdUnitDataInput]
}
AdStat
Description
AdStat represents a day's worth of advertising data.
Example
{
"day": "10:15:30Z",
"clicks": 987,
"impressions": 987,
"price": 987
}
AdUnit
Fields
Field Name | Description |
---|---|
id -
Int!
|
|
name -
String!
|
|
productIds -
[String!]
|
|
monthlyBudgetCents -
Int!
|
|
unitType -
AdUnitType!
|
|
unitData -
AdUnitData!
|
Example
{
"id": 123,
"name": "xyz789",
"productIds": ["xyz789"],
"monthlyBudgetCents": 987,
"unitType": "AUTOBIDDING_SEARCH_UNIT",
"unitData": FixedBidSearchUnitData
}
AdUnitData
Types
Union Types |
---|
Example
FixedBidSearchUnitData
AdUnitDataInput
Fields
Input Field | Description |
---|---|
productId -
String!
|
productId is the product that was clicked in the auction. |
marketplaceUserId -
String
|
marketplaceUserId is an an optional identifier for the user that is logged in when browsing the website. If your users are generally not logged in, you can generate an identifier and use persistent storage client-side to identify the user. |
auctionId -
Int!
|
auctionId is the unique identifier for the auction that this ad is associated with. |
Example
{
"productId": "abc123",
"marketplaceUserId": "abc123",
"auctionId": 123
}
AdUnitType
Values
Enum Value | Description |
---|---|
|
|
|
Example
"AUTOBIDDING_SEARCH_UNIT"
Auction
Fields
Field Name | Description |
---|---|
id -
Int!
|
|
adSlots -
Int!
|
adSlots is the number of ad slots to assign to the winner of the auction |
candidates -
[AuctionCandidate!]
|
candidates is the list of products to enter into the auction. |
marketplaceUserId -
String
|
marketplaceUserId is an an optional identifier for the user that is logged in when browsing the website. If your users are generally not logged in, you can generate an identifier and use persistent storage client-side to identify the user. |
auctionWinners -
[AuctionWinner!]
|
The winners of the auction |
Example
{
"id": 123,
"adSlots": 987,
"candidates": [AuctionCandidate],
"marketplaceUserId": "abc123",
"auctionWinners": [AuctionWinner]
}
AuctionCandidate
Description
AuctionCandidate represents an entrant into a search auction.
Fields
Field Name | Description |
---|---|
productId -
String!
|
productId is the product that is a candidate in this auction. |
searchScore -
Float
|
searchScore is a value between 0 and 1, representing a prior on how relevant the product is to the context of the auction. For example, when running ads, the searchScore can be the score returned by Algolia/Elastic Search. |
Example
{
"productId": "xyz789",
"searchScore": 987.65
}
AuctionCandidateInput
Example
{
"productId": "xyz789",
"searchScore": 987.65
}
AuctionInput
Fields
Input Field | Description |
---|---|
candidates -
[AuctionCandidateInput!]
|
candidates is a list of auction candidates to use in the auction. |
marketplaceUserId -
String
|
marketplaceUserId is an an optional identifier for the user that is logged in when browsing the website. If your users are generally not logged in, you can generate an identifier and use persistent storage client-side to identify the user. |
slots -
Int!
|
slots is the number of winners to pick in the auction. |
Example
{
"candidates": [AuctionCandidateInput],
"marketplaceUserId": "xyz789",
"slots": 123
}
AuctionWinner
Description
AuctionWinner represents a winner of a search auction.
Example
{
"productId": "xyz789",
"adUnitId": 987,
"priceCents": 987
}
AutobiddingSearchUnitData
Fields
Field Name | Description |
---|---|
dailyLimitCents -
Int
|
Example
{"dailyLimitCents": 123}
Boolean
Description
The Boolean
scalar type represents true
or false
.
Example
true
CreateAdUnitInput
CreateAutobiddingSearchAdUnitInput
Fields
Input Field | Description |
---|---|
adUnitInput -
CreateAdUnitInput!
|
The core inputs to create the ad unit. |
dailyBudgetCents -
Int
|
The maximum that an advertiser is willing to spend per day |
Example
{
"adUnitInput": CreateAdUnitInput,
"dailyBudgetCents": 123
}
CreateFixedSearchAdUnitInput
Fields
Input Field | Description |
---|---|
adUnitInput -
CreateAdUnitInput!
|
The core inputs to create the ad unit. |
clickBidCents -
Int!
|
The amount that an advertiser is willing to pay per click. |
Example
{"adUnitInput": CreateAdUnitInput, "clickBidCents": 987}
ExternalData
Description
ExternalData represents a data point that is used by Brist to improve personalized advertising, but isn't associated with an ad that was shown.
Fields
Field Name | Description |
---|---|
time -
Time!
|
The time this event occurred. |
productId -
String!
|
The product that was associated with the event. |
marketplaceUserId -
String
|
marketplaceUserId is an an optional identifier for the user that is logged in when browsing the website. If your users are generally not logged in, you can generate an identifier and use persistent storage client-side to identify the user. |
dataType -
ExternalDataType!
|
The type of event that occured. |
Example
{
"time": "10:15:30Z",
"productId": "xyz789",
"marketplaceUserId": "abc123",
"dataType": "EXTERNAL_CLICK_DATA_TYPE"
}
ExternalDataType
Values
Enum Value | Description |
---|---|
|
Represents when a user clicks a product |
|
Represents when a user purchases a product |
Example
"EXTERNAL_CLICK_DATA_TYPE"
FixedBidSearchUnitData
Fields
Field Name | Description |
---|---|
bidCents -
Int!
|
Example
{"bidCents": 987}
Float
Description
The Float
scalar type represents signed double-precision fractional values as specified by
IEEE 754.
Example
123.45
Int
Description
The Int
scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
Example
123
ProductClickInput
Fields
Input Field | Description |
---|---|
time -
Time
|
The time that this event occurred. If left blank this defaults to the current time. |
productId -
String!
|
productId is the product that was clicked in the auction. |
marketplaceUserId -
String
|
marketplaceUserId is an an optional identifier for the user that is logged in when browsing the website. If your users are generally not logged in, you can generate an identifier and use persistent storage client-side to identify the user. |
Example
{
"time": "10:15:30Z",
"productId": "abc123",
"marketplaceUserId": "xyz789"
}
SelfManagedAdAccountInput
Fields
Input Field | Description |
---|---|
name -
String!
|
Example
{"name": "xyz789"}
String
Description
The String
scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.
Example
"xyz789"
Time
Description
Fields of this type will be a ISO string
Example
"10:15:30Z"
TimeRange
Description
Represents range of times, both endpoints are treated as inclusive, given the resolution given by the Query/Mutation (day, minute, second, etc.).
Example
{
"start": "10:15:30Z",
"end": "10:15:30Z"
}