This document describes how to use the Kakao Moment Report APIs.
Method | URL | Authorization |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/adAccounts/report |
Access token |
Permission | Prerequisite | Kakao Login | User consent |
---|---|---|---|
Required | Register platforms Activate Kakao Login Switch to a Biz app |
Required | - |
This API enables you to retrieve a report on an ad account, including the data of Display campaigns and Message campaigns.
If the request is successful, the API returns the data under the data
field as an array.
This API limits the number of calls you can make to every five seconds per ad account ID and app ID. You cannot make a call within 5 seconds after the last call.
- Because a report on a specific date may be changed until 8:00 A.M on the next day, you need to use the report as the real-time indicator. - If you want to retrieve a report for today in real time, set 'datePreset' to 'TODAY'. To retrieve a report by hour, set 'dimension' to `HOUR`. - Today's date is excluded from the values of 'datePreset' and from the data retrieved by using 'start' and 'end'. - When you set 'start' and 'end' for the search period, the period should be within 31 days. - The maximum search period differs depending on 'timeUnit' (Report counting unit). Report counting unit: DAY, The maximum search period: 1 month - If you want to know data by hour, set 'dimension' to 'HOUR'. - The values of 'dimension' — 'AGE', 'GENDER', 'AGE_GENDER', 'LOCATION', 'DEVICE_TYPE', 'PLACEMENT' — only supports for the Display campaign type. - You can see the values of Display campaigns and Message campaigns in an Ad account report. - You can set multiple values for `metricsGroup` (Report indicator groups). - If an ad account has only Display campaigns and if 'metricsGroup' is set to 'MESSAGE', 'MESSAGE_ADDITION', or 'MESSAGE_CLICK' for the Display campaigns, no data is retrieved. - If an ad account has only Message campaigns and if 'metricsGroup' is set to 'BASIC', 'ADDITION', 'PLUS_FRIEND', 'PIXEL_CONVERSION', 'SDK_CONVERSION' or 'VIDEO' for the Message campaigns, no data is retrieved.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication. |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} Ad account's ID. |
O |
Name | Type | Description | Required |
---|---|---|---|
adAccountId | Long[] |
Ad account's ID to be retrieved. Up to 5 ad accounts are allowed. |
O |
datePreset | DatePreset |
Predefined search period for report Use one of the followings: TODAY , YESTERDAY , LAST_7DAY , LAST_14DAY , LAST_30DAY , THIS_MONTH , LAST_MONTH |
X |
timeUnit | TimeUnit |
Counting unit for report Set it to DAY (Default).NOTE: To retrieve data by hour, use dimension and set it to HOUR . |
X |
start | String |
Report search period (Start date in yyyyMMdd format.) If either start or end is null, data is retrieved according to the value of datePreset . If even datePreset is not specified, data is retrieved based on TODAY (the value of datePreset ).You can set a start date in the past except for the day you search. |
X |
end | String |
Report search period (End date in yyyyMMdd format.) You can set an end date from the start date to the day before you retrieve. |
X |
level | Dimension |
Level criteria to retrieve a report. Set the level you want to retrieve for data grouping. In the ad account-level reports, you can retrieve reports by ad account or by campaign under the ad account. Use one of the followings: AD_ACCOUNT , CAMPAIGN (Default: AD_ACCOUNT ) |
O |
dimension | Dimension |
Criteria to retrieve a report. Set the search criteria for the data you want to retrieve. Use one of the followings: CREATIVE_FORMAT , PLACEMENT , AGE , GENDER , AGE_GENDER , LOCATION , DEVICE_TYPE , HOUR |
X |
metricsGroup | MetricsGroup |
Report metric group. Set the metrics (key performance indicator) you want to retrieve. Use one of the followings: BASIC , ADDITION , MESSAGE , MESSAGE_ADDITION , PIXEL_SDK_CONVERSION , PLUS_FRIEND , VIDEO , SLIDE_CLICK , MESSAGE_CLICK , ADVIEW , BIZ_BOARD , SPB (Default: BASIC ) |
O |
Key | Type | Description |
---|---|---|
code | Integer |
Response code. |
message | String |
Result message. |
data | Data[] |
Detailed data for a report. |
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/report?datePreset=TODAY&level=AD_ACCOUNT&dimension=CREATIVE_FORMAT&metricsGroup=BASIC" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/report?start=20200101&end=20200101&level=AD_ACCOUNT&dimension=CREATIVE_FORMAT&metricsGroup=BASIC" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {
"creative_format": "IMAGE BANNER",
"ad_account_id": "1234"
},
"metrics": {
"imp": 4,
"click": 0,
"ctr": 0.0,
"cost": 0.0
}
}
]
}
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {},
"metrics": {}
}
]
}
Method | URL | Authorization |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/campaigns/report |
Access token |
Permission | Prerequisite | Kakao Login | User consent |
---|---|---|---|
Required | Register platforms Activate Kakao Login Switch to a Biz app |
Required | - |
This API enables you to retrieve reports on campaigns. You can retrieve reports on up to 5 campaigns at once when you request this API.
This API limits the number of calls you can make to every five seconds per ad account ID and app ID. You cannot make a call within 5 seconds after the last call.
- If you set 'metricsGroup' to 'MESSAGE', 'MESSAGE_ADDITION', or 'MESSAGE_CLICK' for a Display campaign, no data is retrieved. - If you set 'metricsGroup' to 'BASIC', 'ADDITION', 'PLUS_FRIEND', 'PIXEL_CONVERSION', 'SDK_CONVERSION' or 'VIDEO' for a Message campaign, no data is retrieved. - For more details on the parameters and response fields, refer to View report on ad account.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication. |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} Ad account's ID. |
O |
Name | Type | Description | Required |
---|---|---|---|
campaignId | Long[] |
Campaign's ID to be retrieved. Up to 5 campaigns are allowed. |
O |
datePreset | DatePreset |
Predefined search period for report Use one of the followings: TODAY , YESTERDAY , LAST_7DAY , LAST_14DAY , LAST_30DAY , THIS_MONTH , LAST_MONTH |
X |
timeUnit | TimeUnit |
Counting unit for report Set it to DAY (Default).NOTE: To retrieve data by hour, use dimension and set it to HOUR . |
X |
start | String |
Report search period (Start date in yyyyMMdd format.) If either start or end is null, data is retrieved according to the value of datePreset . If even datePreset is not specified, data is retrieved based on TODAY (the value of datePreset ).You can set a start date in the past except for the day you search. |
X |
end | String |
Report search period (End date in yyyyMMdd format.) You can set an end date from the start date to the day before you retrieve. |
X |
level | Dimension |
Level criteria to retrieve a report. (Default: CAMPAIGN )Set the level you want to retrieve for data grouping. In the ad account-level reports, you can retrieve reports by ad account or by campaign under the ad account. AD_GROUP , CAMPAIGN |
O |
dimension | Dimension |
Criteria to retrieve a report. Set the search criteria for the data you want to retrieve. Use one of the followings: CREATIVE_FORMAT , PLACEMENT , AGE , GENDER , AGE_GENDER , LOCATION , DEVICE_TYPE , HOUR |
X |
metricsGroup | MetricsGroup |
Report metric group. Set the metrics (key performance indicator) you want to retrieve. Use one of the followings: BASIC , ADDITION , MESSAGE , MESSAGE_ADDITION , PIXEL_SDK_CONVERSION , PLUS_FRIEND , VIDEO , SLIDE_CLICK , MESSAGE_CLICK , ADVIEW , BIZ_BOARD , SPB (Default: BASIC ) |
O |
Key | Type | Description |
---|---|---|
code | Integer |
Response code. |
message | String |
Result message. |
data | Data[] |
Detailed data for a report. |
curl -X GET "https://apis.moment.kakao.com/openapi/v4/campaigns/report?datePreset=TODAY&dimension=CREATIVE_FORMAT&metricsGroup=BASIC&campaignId=11562&level=CAMPAIGN&campaignId=1,2,3,4,5" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
curl -X GET "https://apis.moment.kakao.com/openapi/v4/campaigns/report?start=20200101&end=20200101&dimension=CREATIVE_FORMAT&metricsGroup=BASIC&campaignId=11562&level=CAMPAIGN&campaignId=1,2,3,4,5" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
-H "adAccountId: ${AD_ACCOUNT_ID}"
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {
"creative_format": "IMAGE BANNER",
"campaign_id": "1234"
},
"metrics": {
"imp": 4,
"click": 0,
"ctr": 0.0,
"cost": 0.0
}
},
{
}
]
}
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {},
"metrics": {}
}
]
}
Method | URL | Authorization |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/adGroups/report |
Access token |
Permission | Prerequisite | Kakao Login | User consent |
---|---|---|---|
Required | Register platforms Activate Kakao Login Switch to a Biz app |
Required | - |
This API enables you to retrieve reports on ad groups. You can retrieve reports on up to 20 ad groups at once when you request this API.
This API limits the number of calls you can make to every 5 seconds per ad account ID and app ID. You cannot make a call within 5 seconds after the last call.
- If you set 'metricsGroup' to 'MESSAGE', 'MESSAGE_ADDITION', or 'MESSAGE_CLICK' for a Display ad group, no data is retrieved. - If you set 'metricsGroup' to 'BASIC', 'ADDITION', 'PLUS_FRIEND', 'PIXEL_CONVERSION', 'SDK_CONVERSION' or 'VIDEO' for a Message ad group, no data is retrieved. - For more details on the parameters and response fields, refer to View report on ad account.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication. |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} Ad account's ID. |
O |
Name | Type | Description | Required |
---|---|---|---|
adGroupId | Long[] |
Ad group's ID to be retrieved. Up to 20 ad group are allowed. |
O |
datePreset | DatePreset |
Predefined search period for report Use one of the followings: TODAY , YESTERDAY , LAST_7DAY , LAST_14DAY , LAST_30DAY , THIS_MONTH , LAST_MONTH |
X |
timeUnit | TimeUnit |
Counting unit for report Set it to DAY (Default).NOTE: To retrieve data by hour, use dimension and set it to HOUR . |
X |
start | String |
Report search period (Start date in yyyyMMdd format.) If either start or end is null, data is retrieved according to the value of datePreset . If even datePreset is not specified, data is retrieved based on TODAY (the value of datePreset ).You can set a start date in the past except for the day you search. |
X |
end | String |
Report search period (End date in yyyyMMdd format.) You can set an end date from the start date to the day before you retrieve. |
X |
level | Dimension |
Level criteria to retrieve a report. (Default: AD_GROUP )Set the level you want to retrieve for data grouping. In the ad account-level reports, you can retrieve reports by ad account or by campaign under the ad account. AD_GROUP , CREATIVE |
O |
dimension | Dimension |
Criteria to retrieve a report. Set the search criteria for the data you want to retrieve. Use one of the followings: CREATIVE_FORMAT , PLACEMENT , AGE , GENDER , AGE_GENDER , LOCATION , DEVICE_TYPE , HOUR |
X |
metricsGroup | MetricsGroup |
Report metric group. Set the metrics (key performance indicator) you want to retrieve. Use one of the followings: BASIC , ADDITION , MESSAGE , MESSAGE_ADDITION , PIXEL_SDK_CONVERSION , PLUS_FRIEND , VIDEO , SLIDE_CLICK , MESSAGE_CLICK , ADVIEW , BIZ_BOARD , SPB (Default: BASIC ) |
O |
Key | Type | Description |
---|---|---|
code | Integer |
Response code. |
message | String |
Result message. |
data | Data[] |
Detailed data for a report. |
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/report?datePreset=TODAY&level=AD_GROUP&dimension=CREATIVE_FORMAT&metricsGroup=BASIC&adGroupId=15970&adGroupId=1,2,3,4,5" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
curl -X GET "https://apis.moment.kakao.com/openapi/v4/adGroups/report?start=20200501&end=20200501&level=AD_GROUP&dimension=CREATIVE_FORMAT&metricsGroup=BASIC&adGroupId=15970&adGroupId=1,2,3,4,5" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
-H "adAccountId: ${AD_ACCOUNT_ID}"
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {
"creative_format": "IMAGE BANNER",
"ad_group_id": "1234"
},
"metrics": {
"imp": 4,
"click": 0,
"ctr": 0.0,
"cost": 0.0
}
}
]
}
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {},
"metrics": {}
}
]
}
Method | URL | Authorization |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/creatives/report |
Access token |
Permission | Prerequisite | Kakao Login | User consent |
---|---|---|---|
Required | Register platforms Activate Kakao Login Switch to a Biz app |
Required | - |
This API enables you to retrieve reports on creatives. You can retrieve reports on up to 100 creatives at once when you request this API.
This API limits the number of calls you can make to every 5 seconds per ad account's ID and app's ID. You cannot make a call within 5 seconds after the last call.
- You do not need to set 'level' because this API retrieves only the creative-level of the data. - If you set 'metricsGroup' to 'MESSAGE', 'MESSAGE_ADDITION', or 'MESSAGE_CLICK' for a Display creative, no data is retrieved. - If you set 'metricsGroup' to 'BASIC', 'ADDITION', 'PLUS_FRIEND', 'PIXEL_CONVERSION', 'SDK_CONVERSION' or 'VIDEO' for a Message campaign, no data is retrieved. - For more details on the parameters and response fields, refer to View report on ad account.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication. |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} Ad account's ID. |
O |
Name | Type | Description | Required |
---|---|---|---|
creativeId | Long[] |
Creative's ID to be retrieved. Up to 100 creatives are allowed. |
O |
datePreset | DatePreset |
Predefined search period for report Use one of the followings: TODAY , YESTERDAY , LAST_7DAY , LAST_14DAY , LAST_30DAY , THIS_MONTH , LAST_MONTH |
X |
timeUnit | TimeUnit |
Counting unit for report Set it to DAY (Default).NOTE: To retrieve data by hour, use dimension and set it to HOUR . |
X |
start | String |
Report search period (Start date in yyyyMMdd format.) If either start or end is null, data is retrieved according to the value of datePreset . If even datePreset is not specified, data is retrieved based on TODAY (the value of datePreset ).You can set a start date in the past except for the day you search. |
X |
end | String |
Report search period (End date in yyyyMMdd format.) You can set an end date from the start date to the day before you retrieve. |
X |
dimension | Dimension |
Criteria to retrieve a report. Set the search criteria for the data you want to retrieve. Use one of the followings: CREATIVE_FORMAT , PLACEMENT , AGE , GENDER , AGE_GENDER , LOCATION , DEVICE_TYPE , HOUR |
X |
metricsGroup | MetricsGroup |
Report metric group. Set the metrics (key performance indicator) you want to retrieve. Use one of the followings: BASIC , ADDITION , MESSAGE , MESSAGE_ADDITION , PIXEL_SDK_CONVERSION , PLUS_FRIEND , VIDEO , SLIDE_CLICK , MESSAGE_CLICK , ADVIEW , BIZ_BOARD , SPB (Default: BASIC ) |
O |
Key | Type | Description |
---|---|---|
code | Integer |
Response code. |
message | String |
Result message. |
data | Data[] |
Detailed data for a report. |
curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives/report?datePreset=TODAY&dimension=CREATIVE_FORMAT&metricsGroup=BASIC&creativeId=40068,40065" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives/report?start=20200101&end=20200101&dimension=CREATIVE_FORMAT&metricsGroup=BASIC&level=CREATIVE&creativeId=40068,40065" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {
"creative_format": "IMAGE BANNER",
"creative_id": "1234"
},
"metrics": {
"imp": 4,
"click": 0,
"ctr": 0.0,
"cost": 0.0
}
}
]
}
{
"code": 200,
"message": "Success",
"data": [
{
"start": "2020-01-01",
"end": "2020-01-01",
"dimensions": {},
"metrics": {}
}
]
}