페이지 이동경로
  • 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 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.

IMPORTANT: Ad account report

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

Request

Header
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
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, 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

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

IMPORTANT: 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. - For more details on the parameters and response fields, refer to View report on ad account.

Request

Header
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
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, 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

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

IMPORTANT: 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. - For more details on the parameters and response fields, refer to View report on ad account.

Request

Header
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
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, 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

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

IMPORTANT: 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. - For more details on the parameters and response fields, refer to View report on ad account.

Request

Header
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
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, 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

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 ${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 ${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