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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Returns a report on an ad account.

Report conditions

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.

Rate limit

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 (Maximum: 5 ad accounts).	O
datePreset	`Enum: DatePreset`	Predefined search period for report	X
timeUnit	`Enum: TimeUnit`	Counting unit for report. Available values: `DAY`: Aggregated by date (Default) `ALL`: Aggregated over the entire requested period as one 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	`Enum: Dimension`	Level criteria to retrieve a report (Default: `AD_ACCOUNT`) Available values: `AD_ACCOUNT`: `ad_account_id`: Ad account `CAMPAIGN`: `campaign_id`: Campaign Note: Sets the level at which report data is grouped.	X
dimension	`Enum: Dimension`	Criteria to retrieve a report. Available values: `CREATIVE_FORMAT`: Creative format `PLACEMENT`: Placement `AGE_BAND`: Age range `GENDER`: Gender `AGE_BAND_GENDER`: Age range+gender `LOCATION`: Location `DEVICE_TYPE`: Device type `HOUR`: Hour Note: Sets the criteria by which report data is grouped.	X
metricsGroup	`Enum: MetricsGroup[]`	Report metric group. Available values: `BASIC`: Basic metrics `ADDITION`: Additional metrics `MESSAGE`: Message basic metrics `MESSAGE_ADDITION`: Message additional metrics `MESSAGE_CLICK`: Message click metrics `PLUS_FRIEND`: Kakao Talk friends metrics `PIXEL_SDK_CONVERSION`: Pixel & SDK conversion metrics `SLIDE_CLICK`: Slide metrics `VIDEO`: Video metrics `ADVIEW`: Ad View metrics `BIZ_BOARD`: Bizboard metrics `SPB`: Board metrics Note: Sets the metrics to retrieve. Refer to the type definition for the detailed metrics in each group.	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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Returns reports on campaigns.

Rate limit

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.

Report criteria and response fields

For details on report criteria parameters and response fields, refer to View report on ad account API.

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 (Maximum: 5 campaigns).	O
datePreset	`Enum: DatePreset`	Predefined search period for report	X
timeUnit	`Enum: TimeUnit`	Counting unit for report. Available values: `DAY`: Aggregated by date (Default) `ALL`: Aggregated over the entire requested period as one 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	`Enum: Dimension`	Level criteria to retrieve a report (Default: `CAMPAIGN`) Available values: `CAMPAIGN`: `campaign_id`: Campaign `AD_GROUP`: `ad_group_id`: Ad group Note: Sets the level at which report data is grouped.	X
dimension	`Enum: Dimension`	Criteria to retrieve a report. Available values: `CREATIVE_FORMAT`: Creative format `PLACEMENT`: Placement `AGE_BAND`: Age range `GENDER`: Gender `AGE_BAND_GENDER`: Age range+gender `LOCATION`: Location `DEVICE_TYPE`: Device type `HOUR`: Hour Note: Sets the criteria by which report data is grouped.	X
metricsGroup	`Enum: MetricsGroup[]`	Report metric group. Available values: `BASIC`: Basic metrics `ADDITION`: Additional metrics `MESSAGE`: Message basic metrics `MESSAGE_ADDITION`: Message additional metrics `MESSAGE_CLICK`: Message click metrics `PLUS_FRIEND`: Kakao Talk friends metrics `PIXEL_SDK_CONVERSION`: Pixel & SDK conversion metrics `SLIDE_CLICK`: Slide metrics `VIDEO`: Video metrics `ADVIEW`: Ad View metrics `BIZ_BOARD`: Bizboard metrics `SPB`: Board metrics Note: Sets the metrics to retrieve. Refer to the type definition for the detailed metrics in each group.	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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Returns reports on ad groups.

Rate limit

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 report criteria and response fields, refer to Report criteria and response fields.

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 (Maximum: 40 ad groups).	O
datePreset	`Enum: DatePreset`	Predefined search period for report	X
timeUnit	`Enum: TimeUnit`	Counting unit for report. Available values: `DAY`: Aggregated by date (Default) `ALL`: Aggregated over the entire requested period as one 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	`Enum: Dimension`	Level criteria to retrieve a report (Default: `AD_GROUP`) Available values: `AD_GROUP`: `ad_group_id`: Ad group `CREATIVE`: `creative_id`: Creative Note: Sets the level at which report data is grouped.	X
dimension	`Enum: Dimension`	Criteria to retrieve a report. Available values: `CREATIVE_FORMAT`: Creative format `PLACEMENT`: Placement `AGE_BAND`: Age range `GENDER`: Gender `AGE_BAND_GENDER`: Age range+gender `LOCATION`: Location `DEVICE_TYPE`: Device type `HOUR`: Hour Note: Sets the criteria by which report data is grouped.	X
metricsGroup	`Enum: MetricsGroup[]`	Report metric group. Available values: `BASIC`: Basic metrics `ADDITION`: Additional metrics `MESSAGE`: Message basic metrics `MESSAGE_ADDITION`: Message additional metrics `MESSAGE_CLICK`: Message click metrics `PLUS_FRIEND`: Kakao Talk friends metrics `PIXEL_SDK_CONVERSION`: Pixel & SDK conversion metrics `SLIDE_CLICK`: Slide metrics `VIDEO`: Video metrics `ADVIEW`: Ad View metrics `BIZ_BOARD`: Bizboard metrics `SPB`: Board metrics Note: Sets the metrics to retrieve. Refer to the type definition for the detailed metrics in each group.	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

Requirements		See also
Obtain usage permission Switch to a Biz app	Register business redirect URI Set business consent items	Error code Glossary

Returns reports on creatives.

You can retrieve reports on up to 100 creatives at once.

Rate limit

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.

For report criteria and response fields, refer to Report criteria and response fields.

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 (Maximum: 100 creatives).	O
datePreset	`Enum: DatePreset`	Predefined search period for report	X
timeUnit	`Enum: TimeUnit`	Counting unit for report. Available values: `DAY`: Aggregated by date (Default) `ALL`: Aggregated over the entire requested period as one 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	`Enum: Dimension`	Criteria to retrieve a report. Available values: `CREATIVE_FORMAT`: Creative format `PLACEMENT`: Placement `AGE_BAND`: Age range `GENDER`: Gender `AGE_BAND_GENDER`: Age range+gender `LOCATION`: Location `DEVICE_TYPE`: Device type `HOUR`: Hour Note: Sets the criteria by which report data is grouped.	X
metricsGroup	`Enum: MetricsGroup[]`	Report metric group. Available values: `BASIC`: Basic metrics `ADDITION`: Additional metrics `MESSAGE`: Message basic metrics `MESSAGE_ADDITION`: Message additional metrics `MESSAGE_CLICK`: Message click metrics `PLUS_FRIEND`: Kakao Talk friends metrics `PIXEL_SDK_CONVERSION`: Pixel & SDK conversion metrics `SLIDE_CLICK`: Slide metrics `VIDEO`: Video metrics `ADVIEW`: Ad View metrics `BIZ_BOARD`: Bizboard metrics `SPB`: Board metrics Note: Sets the metrics to retrieve. Refer to the type definition for the detailed metrics in each group.	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

Map

Navigation

Advertisement

Search

More

Report

View report on ad account

Basic information

Report conditions

Rate limit

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

Rate limit

Report criteria and response fields

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

Rate limit

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

Rate limit

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