Skip to main content

API Specification

API docs by Redocly

Ad Insights API (1.0.0)

Download OpenAPI specification:Download

REST API for GameAnalytics Ad Insights, part of the MarketIQ product suite.

Access

The Ad Insights API is available on an invitation basis. To get access, talk to sales.

Base path

All endpoints start with /v1/orgs/{org_id}/adinsights. Replace {org_id} with the ID of your GameAnalytics organization. Your user must have Ad Insights API access for this organization.

For example, to get top products for organization 12345, send:

POST /v1/orgs/12345/adinsights/api/product/top

Authentication

Send a GameAnalytics personal access token (PAT) in the Authorization header of each request. Use the Bearer scheme:

Authorization: Bearer ga_pat.<id>.<key>

Send Content-Type: application/json with each request that has a JSON body.

Refer to the GameAnalyticsPAT security scheme below for more information.

Rate limit and quota

  • Rate limit: Each user can send 1 request each second. If you send more, the API returns 429 with the code too_many_requests. Wait for the time in the Retry-After header, then try again. A request that the rate limit stops does not use the quota.
  • Monthly quota: Each user has a quota of successful requests for each calendar month (UTC), for each organization. The x-quota-limit header gives the quota. A failed request does not use the quota. When you use all of the quota, the API returns 429 with the code quota_exceeded. The quota starts again at the start of the next month.
  • Usage: An owner or an admin of the organization can see the usage of all users in the organization for the current month. Send GET /v1/orgs/{org_id}/adinsights/usage. This request does not use the quota.

Responses from the endpoints include these headers:

Header Description
x-quota-limit The number of successful requests that you can send in one month.
x-quota-remaining The number of successful requests that remain this month.
x-quota-reset The time when the quota starts again, as a Unix timestamp in seconds.
x-request-id The ID of the request. Give this ID when you contact support.

Errors

Each endpoint gives the Ad Insights API response without changes. The Ad Insights API can return HTTP 200 with an error code in the response body. Always examine the code field.

Errors that do not come from the Ad Insights API have this body:

{
  "error": {
    "code": "unauthorized",
    "message": "The PAT is not valid.",
    "request_id": "GH8vYq2k4Zb0Lx0AAAFh",
    "details": {}
  }
}
Status code Cause
400 invalid_body The request body is not valid JSON.
401 unauthorized The Authorization header is missing, or the PAT is not valid.
403 forbidden Your user does not have Ad Insights API access for this organization, or is not a member of it. For the usage endpoint, your user is not an owner or an admin of the organization. details.reason gives the cause.
404 not_found The organization ID is not a positive whole number.
406 not_acceptable The Accept header does not allow application/json.
413 body_too_large The request body is larger than 8 MB.
415 unsupported_media_type The Content-Type header is not application/json.
429 too_many_requests You sent more than 1 request in one second.
429 quota_exceeded You used all of the monthly quota.
502 token_exchange_failed The API could not get an Ad Insights token. If the error continues, contact support.
502 upstream_unavailable The Ad Insights API is not available. Try again later.
503 usage_unavailable The usage endpoint cannot get the usage. Try again later.
504 upstream_timeout The Ad Insights API did not reply in 30 seconds. Try again later.

Get filter field dimension information

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

Request Body schema: application/json
elementType
required
integer

Element category: 1001: Industry, 1002: Asset tag, 1003: Game theme, 1004: New industry classification; 2001: Ad platform, 2002: Global, 2003: Ad title language, 2004: Operating system, 2005: Copy language, 2006: New ad platform, 2007: Major media; 3001: Creative spec (deprecated), 3002: Engagement metric, 3003: Call to action, 3004: Monetization method, 3005: Listing status, 3006: Product type, 3007: Payment type, 3011: Image spec, 3012: Video spec, 3013: Creative type; 4001: Marketing objective, 4002: Site-building tool, 4003: Landing page local format, 4004: Company type, 5001: Ad placement

Responses

Request samples

Content type
application/json
{
  • "elementType": 1004
}

Response samples

Content type
application/json
{
  • "code": "200",
  • "data": [
    ],
  • "traceId": "6d0f02f1-c924-4576-9466-0a60d8d97048",
  • "message": "成功",
  • "jPath": null
}

Get top apps list

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

Request Body schema: application/json
pageIndex
required
integer

Page number

pageSize
required
integer

Items per page

dayMode
string

Date; defaults to 30 days. E.g.: 2023-01 D3 D7 D30

tradeLevel1
Array of strings

Industry type level-1 tag; empty by default. Value comes from the filter-options endpoint where elementType=1004 and level=2 (ccode value).

tradeLevel2
Array of strings

Industry type level-2 tag; empty by default. Value comes from the filter-options endpoint where elementType=1004 and level=3 (ccode value).

tradeLevel3
Array of strings

Industry type level-3 tag; empty by default. Value comes from the filter-options endpoint where elementType=1004 and level=4 (ccode value).

countryLevel2
Array of strings

Level-2 target country; empty by default. Value comes from the filter-options endpoint where elementType=2002 (ccode value).

adfactionIds
Array of strings

Ad platform; empty by default. Value comes from the filter-options endpoint where elementType=2006 (ccode value).

mediaIds
Array of strings

Delivery media; empty by default. Value comes from the filter-options endpoint where elementType=2007 (ccode value).

subMediaIds
Array of strings

Monetization media; empty by default.

device
Array of strings

Operating system; empty by default. Value comes from the filter-options endpoint where elementType=2004 (ccode value).

isNew
boolean

Whether newly added; defaults to false.

searchType
string

Search dimension, i.e. what to search; empty by default. Enum: 1: App/product name/AppID 2: Developer name

keyWord
string

Search keyword; empty by default.

subjectType
Array of strings

Game theme; empty by default. Value comes from the filter-options endpoint where elementType=1003 (ccode value).

sortField
string

Sort rule; three sort options: 1 = creatives found, 2 = most recently found, 3 = days running; choose one.

sortRule
string

Ascending or descending: desc = descending, asc = ascending.

productType
Array of strings

Product category; empty by default. Value comes from the filter-options endpoint where elementType=3006 (ccode value).

selling
Array of strings

Listing status; empty by default. Value comes from the filter-options endpoint where elementType=3005 (ccode value).

monetization
Array of strings

Monetization method; empty by default. Value comes from the filter-options endpoint where elementType=3004 (ccode value).

payType
Array of strings

Payment method; empty by default. Value comes from the filter-options endpoint where elementType=3007 (ccode value).

Responses

Request samples

Content type
application/json
{
  • "pageIndex": 1,
  • "pageSize": 10,
  • "dayMode": "D30",
  • "tradeLevel1": [ ],
  • "tradeLevel2": [ ],
  • "tradeLevel3": [
    ],
  • "countryLevel2": [
    ],
  • "adfactionIds": [
    ],
  • "mediaIds": [ ],
  • "subMediaIds": [ ],
  • "device": [
    ],
  • "isNew": false,
  • "searchType": "1",
  • "keyWord": "Cash’em All: Play & Win",
  • "subjectType": [ ],
  • "productType": [
    ],
  • "selling": [
    ],
  • "monetization": [
    ],
  • "payType": [
    ],
  • "sortField": 1,
  • "sortRule": "desc"
}

Response samples

Content type
application/json
{}

Get top app details

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

query Parameters
productId
required
string
Example: productId=com.xingin.xhs

Product ID

dayMode
string
Example: dayMode=D3

Date; defaults to 30 days. E.g.: 2023-01 D3 D7 D30

Responses

Response samples

Content type
application/json
{}

Get top images list

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

Request Body schema: application/json
keyWord
string

Search keyword; empty by default.

keyWordType
string

Search dimension, i.e. what to search; empty by default. Enum: 0: App/product name/AppID 1: Developer name 2: Ad title/description

isNew
boolean

Whether newly added; defaults to false.

Array of objects

Creative metrics. gs: format qxd: clarity

appealTypeList
Array of strings

Call to action; value comes from the filter-options endpoint where elementType=3003 (ccode value).

languages
Array of strings

Delivery language; empty by default. Value comes from the filter-options endpoint where elementType=2005 (ccode value).

object
required
object
adMediaType
Array of strings

Ad type / ad placement / ad placement media; empty by default. Value comes from the filter-options endpoint where elementType=5001 (ccode value).

Responses

Request samples

Content type
application/json
{
  • "keyWord": "Fortune Greedy Rabbit",
  • "keyWordType": "0",
  • "isNew": false,
  • "creativeList": [
    ],
  • "appealTypeList": [ ],
  • "languages": [
    ],
  • "productOption": {
    },
  • "baseOption": {
    },
  • "adMediaType": [
    ]
}

Response samples

Content type
application/json
{}

Get top image details

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

query Parameters
materialId
required
string
Example: materialId=edfaf1dfdd300b54ba66999b97b95b21

Image asset fingerprint

dayMode
string
Example: dayMode=2023-09

Date; defaults to 30 days. E.g.: 2023-01 D3 D7 D30

Responses

Response samples

Content type
application/json
{
  • "code": "200",
  • "data": {
    },
  • "traceId": "18aecd4a-d5df-4992-8e15-963a5581aab2",
  • "message": null,
  • "jPath": null
}

Get top videos list

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

Request Body schema: application/json
keyWord
string

Search keyword; empty by default.

keyWordType
string

Search dimension, i.e. what to search; empty by default. Enum: 0: App/product name/AppID 1: Developer name 2: Ad title/description 3: Short-drama title

isNew
boolean

Whether newly added; defaults to false.

Array of objects

Creative metrics. gs: format qxd: clarity spsc: video duration

appealTypeList
Array of strings

Call to action; empty by default. Value comes from the filter-options endpoint where elementType=3003 (ccode value).

Array of objects

Engagement metric

languages
Array of strings

Delivery language; empty by default. Value comes from the filter-options endpoint where elementType=2005 (ccode value).

object
required
object
adMediaType
Array of strings

Ad type / ad placement / ad placement media; empty by default. Value comes from the filter-options endpoint where elementType=5001 (ccode value).

Responses

Request samples

Content type
application/json
{
  • "keyWord": "Dots Connect",
  • "keyWordType": "0",
  • "isNew": false,
  • "creativeList": [
    ],
  • "appealTypeList": [ ],
  • "interactionList": [
    ],
  • "languages": [
    ],
  • "productOption": {
    },
  • "baseOption": {
    },
  • "adMediaType": [
    ]
}

Response samples

Content type
application/json
{}

Get top video details

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

query Parameters
materialId
required
string
Example: materialId=148e5ccceb600678e63b36368a5fdca6

Video asset fingerprint

dayMode
string
Example: dayMode=D30

Date; defaults to 30 days. E.g.: 2023-01 D3 D7 D30

Responses

Response samples

Content type
application/json
{}

Get top ad-copy list

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

Request Body schema: application/json
keyWord
string

Search keyword; empty by default.

keyWordType
string

Search dimension, i.e. what to search; empty by default. Enum: 0: App/product name/AppID 1: Developer name 2: Ad title/description

isNew
boolean

Whether newly added; defaults to false.

languages
Array of strings

Delivery language; empty by default. Value comes from the filter-options endpoint where elementType=2005 (ccode value).

object
required
object

Responses

Request samples

Content type
application/json
{
  • "keyWord": "水果汇",
  • "keyWordType": "0",
  • "isNew": false,
  • "languages": [ ],
  • "productOption": {
    },
  • "baseOption": {
    }
}

Response samples

Content type
application/json
{
  • "code": "200",
  • "data": {
    },
  • "traceId": "08c597da-a2c8-4661-bf86-346c22b2dbd3",
  • "message": null,
  • "jPath": null
}

Get top ad-copy details

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

query Parameters
materialId
required
string
Example: materialId=03dffa4423ab8989449a2d4273a68508

Ad-copy fingerprint

dayMode
string
Example: dayMode=D30

Date; defaults to 30 days. E.g.: 2023-01 D3 D7 D30

Responses

Response samples

Content type
application/json
{}

Get top landing-pages list

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

Request Body schema: application/json
keyWord
string

Search dimension, i.e. what to search; empty by default. Enum: 0: App/product name/AppID 1: Developer name 2: Ad title/description

keyWordType
string

Search keyword; empty by default.

isNew
boolean

Whether newly added; defaults to false.

languages
Array of strings

Delivery language; empty by default

required
object
seelTargets
Array of strings

Marketing objective; value comes from the filter-options endpoint where elementType=4001 and level=3 (ccode value).

webTools
Array of strings

Site-building tool; value comes from the filter-options endpoint where elementType=4002 and level=3 (ccode value).

demoadFormats
Array of strings

Landing page format; value comes from the filter-options endpoint where elementType=4003 and level=3 (ccode value).

Responses

Request samples

Content type
application/json
{
  • "keyWord": "Atlas Earth－Own Metaverse Land",
  • "keyWordType": "0",
  • "isNew": false,
  • "baseOption": {
    },
  • "seelTargets": [ ],
  • "webTools": [ ],
  • "demoadFormats": [ ],
  • "adMediaType": [ ]
}

Response samples

Content type
application/json
{}

Get top landing-page details

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

query Parameters
materialId
required
string
Example: materialId=04805b9d063a631bb8632a188456fd47750bf5d8

Landing-page fingerprint

dayMode
string
Example: dayMode=D30

Date; defaults to 30 days. E.g.: 2023-01 D3 D7 D30

Responses

Response samples

Content type
application/json
{
  • "code": "200",
  • "data": {
    },
  • "traceId": "b83af5d0-7352-4fcc-9807-44926c9d05d1",
  • "message": null,
  • "jPath": null
}

Get top playables list

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

Request Body schema: application/json
keyWord
string

Search dimension, i.e. what to search; empty by default. Enum: 0: App/product name/AppID 1: Developer name 2: Ad title/description

keyWordType
string

Search keyword; empty by default.

isNew
boolean

Whether newly added; defaults to false.

languages
Array of strings

Delivery language; empty by default

required
object

Responses

Request samples

Content type
application/json
{
  • "keyWord": "JustPlay - Loyalty Program",
  • "keyWordType": "0",
  • "isNew": false,
  • "languages": [ ],
  • "baseOption": {
    }
}

Response samples

Content type
application/json
{}

Get top playable details

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

query Parameters
materialId
required
string
Example: materialId=0398cc7f6561e50030264e2edc0c4bf0

Playable fingerprint

dayMode
string
Example: dayMode=D30

Date; defaults to 30 days. E.g.: 2023-01 D3 D7 D30

Responses

Response samples

Content type
application/json
{
  • "code": "200",
  • "data": {
    },
  • "traceId": "c63da3fe-bfe0-4091-bf06-476bed8b6ca0",
  • "message": null,
  • "jPath": null
}

Get download apps list – single package

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

Request Body schema: application/json
queryStartDate
string

Start time; defaults to the last 30 days; format yyyy-MM-dd, e.g. 2025-01-01.

queryEndDate
string

End time; defaults to the last 30 days; format yyyy-MM-dd, e.g. 2025-01-01.

If queryStartDate and queryEndDate are more than 30 days apart, results are calculated for the 30 days preceding queryEndDate.

required
object
object
countrySt
Array of strings

Target country/region

Responses

Request samples

Content type
application/json
{
  • "queryStartDate": "2026-01-01",
  • "queryEndDate": "2026-01-30",
  • "baseOption": {
    },
  • "productOption": {
    },
  • "countrySt": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "traceId": "7cc68e4c-96d5-4b40-b7ed-44bc64dfb50f",
  • "message": null,
  • "msg": null,
  • "jPath": null
}

Get download apps list – unified

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

Request Body schema: application/json
queryStartDate
string

Start time; defaults to the last 30 days; format yyyy-MM-dd, e.g. 2025-01-01.

queryEndDate
string

End time; defaults to the last 30 days; format yyyy-MM-dd, e.g. 2025-01-01.

If queryStartDate and queryEndDate are more than 30 days apart, results are calculated for the 30 days preceding queryEndDate.

required
object
object
countrySt
Array of strings

Target country/region

Responses

Request samples

Content type
application/json
{
  • "baseOption": {
    }
}

Response samples

Content type
application/json
{}

Get download app details

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

Request Body schema: application/json
pkgId
required
string

Product ID

productType
required
integer

Product type: 1 = single package, 2 = unified package

queryStartDate
string

Start time; defaults to the last 30 days; format yyyy-MM-dd, e.g. 2025-01-01.

queryEndDate
string

End time; defaults to the last 30 days; format yyyy-MM-dd, e.g. 2025-01-01.

If queryStartDate and queryEndDate are more than 30 days apart, results are calculated for the 30 days preceding queryEndDate.

countrySt
Array of strings

Target country/region; the size for this parameter is limited to 5 — if exceeded, only the first 5 countries/regions are queried.

Responses

Request samples

Content type
application/json
{
  • "pkgId": "1482155847",
  • "productType": 1,
  • "queryStartDate": "2026-01-01",
  • "queryEndDate": "2026-01-30",
  • "countrySt": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "data": {
    },
  • "traceId": "2f95ebe8-ad72-4b4f-a96c-abf947ed3f7a",
  • "message": null,
  • "msg": null,
  • "jPath": null
}

Get monthly usage of the organization

Gives the number of successful requests that each user in the organization sent in the current month (UTC). Use this endpoint to monitor the usage of your team.

Only an owner or an admin of the organization can use this endpoint. This request does not use the quota, but the rate limit applies.

Authorizations:
GameAnalyticsPAT
path Parameters
org_id
required
integer <int64> >= 1
Example: 12345

The ID of your GameAnalytics organization.

Responses

Response samples

Content type
application/json
{
  • "org_id": 12345,
  • "month": "2026-10",
  • "limit": 1000,
  • "reset_at": "2026-11-01T00:00:00Z",
  • "users": [
    ]
}