Kakao Moment

Report

This document describes how to use the Kakao Moment Report APIs.

View report on ad account

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/adAccounts/report`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves a report on an ad account, including the data of Display campaigns and Message campaigns.

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).

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.

If the request is successful, the API returns the data under the data field as an array.

This API limits the number of calls to every five seconds per ad account ID for a single report or app ID for multiple reports. You cannot make a call within 5 seconds after the last call.

Ad account report

The values of dimension — AGE, GENDER, AGE_GENDER, LOCATION, DEVICE_TYPE, PLACEMENT — only supports for the Display campaign type.
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.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID. Required when requesting a report with only one ad account ID.	X

Query parameter

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_BAND`, `GENDER`, `AGE_BAND_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

Response

Body

Key	Type	Description
code	`Integer`	Error code.
message	`String`	Result message.
data	`Data[]`	Detailed data for a report.

Sample

Request: with datePreset

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 ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}"

Request: without datePreset

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 ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}"

Response

{
  "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
      }
    }
  ]
}

Response: If no report data exists

{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "start": "2020-01-01",
      "end": "2020-01-01",
      "dimensions": {},
      "metrics": {}
    }
  ]
}

View reports on campaigns

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/campaigns/report`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves reports on campaigns.

You can retrieve reports on up to 5 campaigns at once when you request this API. For more details on the parameters and response fields, refer to View report on ad account.

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.

Campaign report

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.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Query parameter

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_BAND`, `GENDER`, `AGE_BAND_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

Response

Body

Key	Type	Description
code	`Integer`	Error code.
message	`String`	Result message.
data	`Data[]`	Detailed data for a report.

Sample

Request: with datePreset

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 ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}"

Request: without datePreset

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 ${BUSINESS_ACCESS_TOKEN}"
-H "adAccountId: ${AD_ACCOUNT_ID}"

Response

{
  "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
      }
    },
    {}
  ]
}

Response: If no report data exists

{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "start": "2020-01-01",
      "end": "2020-01-01",
      "dimensions": {},
      "metrics": {}
    }
  ]
}

View reports on ad groups

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/adGroups/report`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves reports on ad groups.

This API limits the number of calls you can make to every one second per ad account ID and app ID. You cannot make a call within 1 second after the last call.

For more details on the parameters and response fields, refer to View report on ad account.

Ad group report

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.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Query parameter

Name	Type	Description	Required
adGroupId	`Long[]`	Ad group's ID to be retrieved. A maximum of 40 ad groups can be retrieved at once.	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_BAND`, `GENDER`, `AGE_BAND_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

Response

Body

Key	Type	Description
code	`Integer`	Error code.
message	`String`	Result message.
data	`Data[]`	Detailed data for a report.

Sample

Request: with datePreset

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 ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}"

Request: without datePreset

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 ${BUSINESS_ACCESS_TOKEN}"
-H "adAccountId: ${AD_ACCOUNT_ID}"

Response

{
  "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
      }
    }
  ]
}

Response: If no report data exists

{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "start": "2020-01-01",
      "end": "2020-01-01",
      "dimensions": {},
      "metrics": {}
    }
  ]
}

View reports on creatives

Basic information

Method	URL	Authorization
`GET`	`https://apis.moment.kakao.com/openapi/v4/creatives/report`	Business token

Permission	Prerequisite	Business Authentication	Business consent items
Required: Request permission	Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Retrieves reports on creatives.

You can retrieve reports on up to 100 creatives at once when you request this API. For more details on the parameters and response fields, refer to View report on ad account.

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.

Creative report

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.

Request

Header

Name	Description	Required
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` Business token as a type of user authentication.	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` Ad account's ID.	O

Query parameter

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_BAND`, `GENDER`, `AGE_BAND_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

Response

Body

Key	Type	Description
code	`Integer`	Error code.
message	`String`	Result message.
data	`Data[]`	Detailed data for a report.

Sample

Request: with datePreset

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 ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}"

Request: without datePreset

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 ${BUSINESS_ACCESS_TOKEN}" \
  -H "adAccountId: ${AD_ACCOUNT_ID}"

Response

{
  "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
      }
    }
  ]
}

Response: If no report data exists

{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "start": "2020-01-01",
      "end": "2020-01-01",
      "dimensions": {},
      "metrics": {}
    }
  ]
}

See more

Kakao Moment API Reference

사이드 메뉴

Docs Home

Getting started

Kakao Developers

Login

Communication

Kakao Map

Navigation

Advertisement

Search

More

Report

View report on ad account

Basic information

Request

Header

Query parameter

Response

Body

Sample

Request: with datePreset

Request: without datePreset

Response

Response: If no report data exists

View reports on campaigns

Basic information

Request

Header

Query parameter

Response

Body

Sample

Request: with datePreset

Request: without datePreset

Response

Response: If no report data exists

View reports on ad groups

Basic information

Request

Header

Query parameter

Response

Body

Sample

Request: with datePreset

Request: without datePreset

Response

Response: If no report data exists

View reports on creatives

Basic information

Request

Header

Query parameter

Response

Body

Sample

Request: with datePreset

Request: without datePreset

Response

Response: If no report data exists

See more

Was this helpful?

Report

View report on ad account

View reports on campaigns

View reports on ad groups

View reports on creatives

See more