Note: The Marketing API is in Alpha and undergoing active development. Availability is not guaranteed and significant changes may still be made.
Advertisers: Examples
To help get you on the right track, below are some example queries / mutations.
- Update a bid
- Look up ad sets
- Look up insights
- Look up user time zones
- Look up configured events
- Look up per-app event configurations
Update a bid
mutation {
updateAdSet(input: {
id: "00000000-0000-0000-0000-000000000000",
bidding: {amount: 1000000}
}) {
adSet {
id
}
}
}
{
"data": {
"adSet": {
"id": "00000000-0000-0000-0000-000000000000"
}
}
}
Note that the bid amount in this case is represented in micros. For more
information, see the documentation for the Money
scalar type.
References:
- updateAdSet mutation
- BiddingInput type
- AdSet type
Look up ad sets
References:
- Advertiser#adSets field
- AdSet type
No filtering
query {
advertiser {
adSets(first: 50) {
edges {
node {
id
bidding {
amount
}
campaign {
objective
}
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
{
"data": {
"advertiser": {
"adSets": {
"edges": [
{
"node": {
"id": "00000000-0000-0000-0000-000000000000",
"bidding": {
"amount": 0.02
},
"campaign": {
"objective": "VIEWS"
}
}
},
{
"node": {
"id": "00000000-0000-0000-0000-000000000001",
"bidding": {
"amount": 0.04
},
"campaign": {
"objective": "VIEWS"
}
}
}
],
"pageInfo": {
"endCursor": "Mg==",
"hasNextPage": false
}
}
}
}
}
Note that you can use the endCursor from the above response to request the
next page. For example:
query {
advertiser {
adSets(first: 50, after: "Mg==") {
edges {
node {
id
bidding {
amount
}
campaign {
objective
}
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
{
"data": {
"advertiser": {
"adSets": {
"edges": [
{
"node": {
"id": "00000000-0000-0000-0000-000000000051",
"bidding": {
"amount": 0.02
},
"campaign": {
"objective": "VIEWS"
}
}
},
{
"node": {
"id": "00000000-0000-0000-0000-000000000052",
"bidding": {
"amount": 0.04
},
"campaign": {
"objective": "VIEWS"
}
}
}
],
"pageInfo": {
"endCursor": "Pf==",
"hasNextPage": false
}
}
}
}
}
With filtering
query {
advertiser {
adSets(first: 50, configuredStatus: ACTIVE) {
edges {
node {
id
}
}
}
}
}
{
"data": {
"advertiser": {
"adSets": {
"edges": [
{
"node": {
"id": "00000000-0000-0000-0000-000000000000"
}
},
{
"node": {
"id": "00000000-0000-0000-0000-000000000001"
}
}
]
}
}
}
}
Look up insights
References:
- AdSet#insights field
- AdInsight type
- AdInsightsData type
No breakdown
query {
adSet(id: "00000000-0000-0000-0000-000000000000") {
insights(timeRange: {from: "2018-03-06T00:00:00Z", until: "2018-03-07T00:00:00Z"}) {
timestamps
reports {
impressions
conversions
spend
}
}
}
}
{
"data": {
"adSet": {
"insights": {
"timestamps": [
"2018-03-06T00:00:00Z"
],
"reports": [
{
"impressions": [
13550
],
"conversions": [
53
],
"spend": [
159000000
]
}
]
}
}
}
}
Breakdown by country
query {
adSet(id: "00000000-0000-0000-0000-000000000000") {
insights(timePreset: TODAY) {
reports {
country
impressions
conversions
spend
}
}
}
}
{
"data": {
"adSet": {
"insights": {
"reports": [
{
"country": "US",
"impressions": [
6147
],
"conversions": [
24
],
"spend": [
73000000
]
},
{
"country": "UK",
"impressions": [
7403
],
"conversions": [
29
],
"spend": [
86000000
]
}
]
}
}
}
}
Breakdown by Ad and Publisher App
Note: Data before October 15th, 2018 will not have an app associated with it. In this case, "app" will simply be "null" (example in the results tab).
Note: bundleId and storeId are only available after contacting Tapjoy. hashedId is an encrypted unique identifier for each app.
query {
adSet(id: "00000000-0000-0000-0000-000000000000") {
ads {
id
insights(timePreset: TODAY) {
reports {
app {
bundleId
hashedId
}
impressions
conversions
spend
}
}
}
}
}
{
"data": {
"adSet": {
"ads": [
{
"id": "10000000-0000-0000-0000-000000000000",
"insights": {
"reports": [
{
"app": {
"bundleId": "com.example.app",
"hashedId": "6672d67337c4e4772caed7eab4f27e7fd247aa99b33b83cc42c1c223a8d8d7"
},
"impressions": [
6147
],
"conversions": [
24
],
"spend": [
73000000
]
},
{
"app": {
"bundleId": "com.example.app2",
"hashedId": "1e51de2b1db10655a7f00810ddf087dcbdc2f6be525b2f44ea4c8062f7230e0"
},
"impressions": [
4131
],
"conversions": [
12
],
"spend": [
73000000
]
},
{
"app": null,
"impressions": [
5427
],
"conversions": [
34
],
"spend": [
73000000
]
}
]
}
},
{
"id": "20000000-0000-0000-0000-000000000000",
"insights": {
"reports": [
{
"app": {
"bundleId": "com.example.app",
"hashedId": "6672d67337c4e4772caed7eab4f27e7fd247aa99b33b83cc42c1c223a8d8d7"
},
"impressions": [
6142
],
"conversions": [
24
],
"spend": [
73000000
]
},
{
"app": {
"bundleId": "com.example.app2",
"hashedId": "1e51de2b1db10655a7f00810ddf087dcbdc2f6be525b2f44ea4c8062f7230e0"
},
"impressions": [
4111
],
"conversions": [
12
],
"spend": [
73000000
]
},
{
"app": null,
"impressions": [
5227
],
"conversions": [
30
],
"spend": [
73000000
]
}
]
}
}
],
"insights": {
"reports": [
{
"app": {
"bundleId": "com.example.app",
"hashedId": "6672d67337c4e4772caed7eab4f27e7fd247aa99b33b83cc42c1c223a8d8d7"
},
"impressions": [
12550
],
"conversions": [
49
],
"spend": [
147000000
]
},
{
"app": {
"bundleId": "com.example.app2",
"hashedId": "1e51de2b1db10655a7f00810ddf087dcbdc2f6be525b2f44ea4c8062f7230e0"
},
"impressions": [
8242
],
"conversions": [
24
],
"spend": [
146000000
]
},
{
"app": null,
"impressions": [
10654
],
"conversions": [
64
],
"spend": [
146000000
]
}
]
}
}
}
}
Across all Ad Sets
query {
advertiser {
adSets(first: 50, configuredStatus: ACTIVE) {
edges {
node {
id
insights(timeRange: {from: "2018-03-06T00:00:00Z", until: "2018-03-07T00:00:00Z"}) {
timestamps
reports {
conversions
spend
}
}
}
}
}
}
}
{
"data": {
"advertiser": {
"adSets": {
"edges": [
{
"node": {
"id": "00000000-0000-0000-0000-000000000000",
"insights": {
"timestamps": [
"2018-03-06T00:00:00Z"
],
"reports": [
{
"impressions": [
13550
],
"conversions": [
53
],
"spend": [
159000000
]
}
]
}
}
},
{
"node": {
"id": "00000000-0000-0000-0000-000000000001",
"insights": {
"timestamps": [
"2018-03-06T00:00:00Z"
],
"reports": [
{
"impressions": [
1220
],
"conversions": [
8
],
"spend": [
12300000
]
}
]
}
}
}
]
}
}
}
}
Look up user time zones
References:
- User type
- User#timeZone field
- TimeZone type
Note that utcOffset is +/- the number of hours and minutes that the time zone is from UTC. If the time zone is UTC, it will be returned as +00:00.
Additionally, information will change based on if the time zone is currently experiencing daylight savings time. For example you may see EDT or EST for Eastern Time's abbreviation.
query {
user {
firstName
lastName
timeZone {
utcOffset
name
abbreviation
}
}
}
{
"data": {
"user": {
"firstName": "Jane",
"lastName": "Doe",
"timeZone": {
"utcOffset": "-05:00",
"name": "Eastern Time (US & Canada)",
"abbreviation": "EDT"
}
}
}
}
Look up configured events
References:
This lists all multiRewardEngagementEvents on an adset, regardless of bid amount, status, or number of conversions.
{
adSet(id: "ace4b134-c5ab-4e97-bc81-95406682682c") {
multiRewardEngagementSettings {
events {
eventName
eventValue
amount
}
}
}
}
{
"data": {
"adSet": {
"multiRewardEngagementSettings": [
{
"events": [
{
"eventName": "level_#",
"eventValue": "5",
"amount": 0
},
{
"eventName": "level_#",
"eventValue": "10",
"amount": 480000
},
{
"eventName": "level_#",
"eventValue": "30",
"amount": 1560000
},
{
"eventName": "level_#",
"eventValue": "50",
"amount": 2440000
},
{
"eventName": "level_#",
"eventValue": "70",
"amount": 3320000
}
]
}
]
}
}
}
Look up per-app event configurations
References:
- MultiRewardEngagementEvent type
- AppReference type
This lists all multiRewardEngagementEvents data on an adSet, including publisher-app-specific bid settings. Non-publisher-app-specific event configurations will be listed under the null app.
{
adSet(id: "ace4b134-c5ab-4e97-bc81-95406682682c") {
multiRewardEngagementSettings {
app {
bundleId
}
events {
eventName
eventValue
amount
}
}
}
}
{
"data": {
"adSet": {
"multiRewardEngagementSettings": [
{
"app": null,
"events": [
{
"eventName": "level_#",
"eventValue": "5",
"amount": 0
},
{
"eventName": "level_#",
"eventValue": "10",
"amount": 480000
},
{
"eventName": "level_#",
"eventValue": "30",
"amount": 1560000
},
{
"eventName": "level_#",
"eventValue": "50",
"amount": 2440000
},
{
"eventName": "level_#",
"eventValue": "70",
"amount": 3320000
}
]
},
{
"app": {
"bundleId": "com.app.example"
},
"events": [
{
"eventName": "level_#",
"eventValue": "10",
"amount": 520000
},
{
"eventName": "level_#",
"eventValue": "30",
"amount": 1680000
},
{
"eventName": "level_#",
"eventValue": "50",
"amount": 2624000
},
{
"eventName": "level_#",
"eventValue": "70",
"amount": 3576000
}
]
}
]
}
}
}