페이지 이동경로
  • Docs>
  • Kakao Moment>
  • Report

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

This API enables you to retrieve 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.

Note: Ad account report

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

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

Note: Campaign report

1. If you set metricsGroup to 'MESSAGE', 'MESSAGE_ADDITION', or 'MESSAGE_CLICK' for a Display campaign, no data is retrieved. 2. 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 Response 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

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. 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 ID and app ID. You cannot make a call within 5 seconds after the last call.

Note: Ad group report

1. If you set metricsGroup to 'MESSAGE', 'MESSAGE_ADDITION', or 'MESSAGE_CLICK' for a Display ad group, no data is retrieved. 2. 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.

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_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 Response 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

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

Note: Creative report

1. You do not need to set 'level' because this API retrieves only the creative-level of the data. 2. If you set metricsGroup to 'MESSAGE', 'MESSAGE_ADDITION', or 'MESSAGE_CLICK' for a Display creative, no data is retrieved. 3. 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 Response 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> Report