Seven read operations returning analytics for a LINE Official Account — friend demographics, number of followers, number of message deliveries by day, per-request message event statistics (impressions, clicks, per-link breakdown), statistics per aggregation unit, and rich menu insight totals and daily series.
---
openapi: 3.0.0
info:
title: LINE Messaging API(Insight)
version: "0.0.1"
description:
This document describes LINE Messaging API(Insight).
servers:
- url: "https://api.line.me"
security:
- Bearer: []
tags:
- name: insight
paths:
"/v2/bot/insight/demographic":
get:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-demographic
tags:
- insight
operationId: getFriendsDemographics
description: |+
Retrieves the demographic attributes for a LINE Official Account's
friends.You can only retrieve information about friends for LINE Official
Accounts created by users in Japan (JP), Thailand (TH), Taiwan (TW) and Indonesia
(ID).
responses:
"200":
content:
"application/json":
schema:
$ref: "#/components/schemas/GetFriendsDemographicsResponse"
example:
available: true
genders:
- gender: unknown
percentage: 37.6
- gender: male
percentage: 31.8
- gender: female
percentage: 30.6
ages:
- age: unknown
percentage: 37.6
- age: from50
percentage: 17.3
areas:
- area: unknown
percentage: 42.9
- area: 徳島
percentage: 2.9
appTypes:
- appType: ios
percentage: 62.4
- appType: android
percentage: 27.7
- appType: others
percentage: 9.9
subscriptionPeriods:
- subscriptionPeriod: over365days
percentage: 96.4
- subscriptionPeriod: within365days
percentage: 1.9
- subscriptionPeriod: within180days
percentage: 1.2
- subscriptionPeriod: within90days
percentage: 0.5
- subscriptionPeriod: within30days
percentage: 0.1
- subscriptionPeriod: within7days
percentage: 0
description: "OK"
"/v2/bot/insight/message/delivery":
get:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-number-of-delivery-messages
tags:
- insight
operationId: getNumberOfMessageDeliveries
description: |+
Returns the number of messages sent from LINE Official Account
on a specified day.
parameters:
- in: query
name: date
description: |+
Date for which to retrieve number of sent messages.
- Format: yyyyMMdd (e.g. 20191231)
- Timezone: UTC+9
required: true
schema:
type: string
pattern: "^[0-9]{8}$"
minLength: 8
maxLength: 8
responses:
"200":
content:
"application/json":
schema:
$ref: "#/components/schemas/GetNumberOfMessageDeliveriesResponse"
example:
status: ready
broadcast: 5385
targeting: 522
description: "OK"
summary: "Get number of message deliveries"
"/v2/bot/insight/followers":
get:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-number-of-followers
tags:
- insight
summary: "Get number of followers"
description: |+
Returns the number of users who have added the LINE Official Account
on or before a specified date.
operationId: getNumberOfFollowers
parameters:
- in: query
name: date
required: false
description: |+
Date for which to retrieve the number of followers.
Format: yyyyMMdd (e.g. 20191231)
Timezone: UTC+9
schema:
type: string
pattern: "^[0-9]{8}$"
maxLength: 8
minLength: 8
responses:
"200":
description: "OK"
content:
"application/json":
schema:
$ref: "#/components/schemas/GetNumberOfFollowersResponse"
example:
status: ready
followers: 7620
targetedReaches: 5848
blocks: 237
"/v2/bot/insight/message/event":
get:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-message-event
tags:
- insight
description: |+
Returns statistics about how users interact with narrowcast messages
or broadcast messages sent from your LINE Official Account.
summary: "Get user interaction statistics"
operationId: getMessageEvent
parameters:
- in: query
name: requestId
required: true
description: |+
Request ID of a narrowcast message or broadcast message.
Each Messaging API request has a request ID.
schema:
# TODO maxLength and/or pattern is required for x-line-request-id
type: string
minLength: 1
responses:
"200":
description: "OK"
content:
"application/json":
schema:
$ref: "#/components/schemas/GetMessageEventResponse"
example:
overview:
requestId: f70dd685-499a-4231-a441-f24b8d4fba21
timestamp: 1568214000
delivered: 320
uniqueImpression: 82
uniqueClick: 51
uniqueMediaPlayed:
uniqueMediaPlayed100Percent:
messages:
- seq: 1
impression: 136
mediaPlayed:
mediaPlayed25Percent:
mediaPlayed50Percent:
mediaPlayed75Percent:
mediaPlayed100Percent:
uniqueMediaPlayed:
uniqueMediaPlayed25Percent:
uniqueMediaPlayed50Percent:
uniqueMediaPlayed75Percent:
uniqueMediaPlayed100Percent:
clicks:
- seq: 1
url: https://line.me/
click: 41
uniqueClick: 30
uniqueClickOfRequest: 30
- seq: 1
url: https://www.linebiz.com/
click: 59
uniqueClick: 38
uniqueClickOfRequest: 38
"/v2/bot/insight/message/event/aggregation":
get:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-statistics-per-unit
tags:
- insight
description: |+
You can check the per-unit statistics of how users interact with
push messages and multicast messages sent from your LINE Official Account.
operationId: getStatisticsPerUnit
parameters:
- in: query
name: customAggregationUnit
required: true
description: |+
Name of aggregation unit specified when sending the message. Case-sensitive.
For example, `Promotion_a` and `Promotion_A` are regarded as different unit names.
schema:
type: string
pattern: "^[a-zA-Z0-9_]{1,30}$"
minLength: 1
maxLength: 30
- in: query
name: from
required: true
description: |+
Start date of aggregation period.
Format: yyyyMMdd (e.g. 20210301)
Time zone: UTC+9
schema:
type: string
pattern: "^[0-9]{8}$"
example: "20210301"
minLength: 8
maxLength: 8
- in: query
name: to
required: true
description: |+
End date of aggregation period. The end date can be specified for up to 30 days later. For example, if the start date is 20210301, the latest end date is 20210331.
Format: yyyyMMdd (e.g. 20210301)
Time zone: UTC+9
schema:
type: string
pattern: "^[0-9]{8}$"
example: "20210301"
minLength: 8
maxLength: 8
responses:
"200":
description: "OK"
content:
"application/json":
schema:
$ref: "#/components/schemas/GetStatisticsPerUnitResponse"
example:
overview:
uniqueImpression: 40
uniqueClick: 30
uniqueMediaPlayed: 25
uniqueMediaPlayed100Percent: ~
messages:
- seq: 1
impression: 42
mediaPlayed: 30
mediaPlayed25Percent: ~
mediaPlayed50Percent: ~
mediaPlayed75Percent: ~
mediaPlayed100Percent: ~
uniqueMediaPlayed: 25
uniqueMediaPlayed25Percent: ~
uniqueMediaPlayed50Percent: ~
uniqueMediaPlayed75Percent: ~
uniqueMediaPlayed100Percent: ~
clicks:
- seq: 1
url: https://developers.line.biz/
click: 35
uniqueClick: 25
uniqueClickOfRequest: ~
- seq: 1
url: https://developers.line.biz/
click: 29
uniqueClick: ~
uniqueClickOfRequest: ~
"/v2/bot/insight/richmenu/{richMenuId}/summary":
get:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-rich-menu-insight-summary
tags:
- insight
operationId: getRichMenuInsightSummary
summary: "Get rich menu insight summary"
description: |+
Gets a summary of rich menu statistics for the specified period, for a rich
menu created via the Messaging API. Returns the total impression count for
the whole rich menu and the click count for each tappable area, aggregated
over the entire period as a single result.
When the total number of unique clicks during the period is below the
privacy threshold, only `richMenuId` is returned and the other fields are
omitted.
parameters:
- in: path
name: richMenuId
required: true
description: "ID of the rich menu created via the Messaging API."
schema:
type: string
example: "richmenu-0123456789abcdef0123456789abcdef"
- in: query
name: from
required: true
description: |+
Start date of the aggregation period (inclusive).
Must be within the most recent 3 years.
Format: yyyyMMdd (e.g. 20260213)
Time zone: UTC+9
schema:
type: string
pattern: "^[0-9]{8}$"
example: "20260213"
minLength: 8
maxLength: 8
- in: query
name: to
required: true
description: |+
End date of the aggregation period (inclusive).
The end date can be specified for up to 396 days after the start date.
Format: yyyyMMdd (e.g. 20260215)
Time zone: UTC+9
schema:
type: string
pattern: "^[0-9]{8}$"
example: "20260215"
minLength: 8
maxLength: 8
responses:
"200":
description: "OK"
content:
"application/json":
schema:
$ref: "#/components/schemas/GetRichMenuInsightSummaryResponse"
examples:
default:
summary: "Statistics are available"
value:
richMenuId: "richmenu-0123456789abcdef0123456789abcdef"
metricsFrom: "20260213"
metricsTo: "20260215"
impression:
metrics:
count: 567
uniqueUsers: 300
clicks:
- bounds:
x: 0
y: 0
width: 400
height: 250
metrics:
count: 123
uniqueUsers: 45
- bounds:
x: 400
y: 0
width: 400
height: 250
metrics:
count: 45
uniqueUsers: 24
belowThreshold:
summary: "Returned when the total number of unique clicks is below the privacy threshold"
value:
richMenuId: "richmenu-0123456789abcdef0123456789abcdef"
"400":
description: "Bad request. The `from` or `to` parameter is missing or invalid, or the aggregation period exceeds the allowed maximum."
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorResponse"
"404":
description: "Not found. The specified rich menu does not exist."
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorResponse"
"/v2/bot/insight/richmenu/{richMenuId}/daily":
get:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-rich-menu-insight-daily
tags:
- insight
operationId: getRichMenuInsightDaily
summary: "Get rich menu insight daily"
description: |+
Gets rich menu statistics broken down by day for the specified period, for a
rich menu created via the Messaging API. Returns the daily impression count
for the whole rich menu and the daily click count for each tappable area.
When the total number of unique clicks during the period is below the
privacy threshold, only `richMenuId` is returned and the other fields are
omitted.
parameters:
- in: path
name: richMenuId
required: true
description: "ID of the rich menu created via the Messaging API."
schema:
type: string
example: "richmenu-0123456789abcdef0123456789abcdef"
- in: query
name: from
required: true
description: |+
Start date of the aggregation period (inclusive).
Must be within the most recent 3 years.
Format: yyyyMMdd (e.g. 20260213)
Time zone: UTC+9
schema:
type: string
pattern: "^[0-9]{8}$"
example: "20260213"
minLength: 8
maxLength: 8
- in: query
name: to
required: true
description: |+
End date of the aggregation period (inclusive).
The end date can be specified for up to 99 days after the start date.
Format: yyyyMMdd (e.g. 20260215)
Time zone: UTC+9
schema:
type: string
pattern: "^[0-9]{8}$"
example: "20260215"
minLength: 8
maxLength: 8
responses:
"200":
description: "OK"
content:
"application/json":
schema:
$ref: "#/components/schemas/GetRichMenuInsightDailyResponse"
examples:
default:
summary: "Statistics are available"
value:
richMenuId: "richmenu-0123456789abcdef0123456789abcdef"
metricsFrom: "20260213"
metricsTo: "20260215"
impression:
metrics:
- date: "20260213"
count: 300
uniqueUsers: 191
- date: "20260214"
count: 267
uniqueUsers: 222
clicks:
- bounds:
x: 0
y: 0
width: 400
height: 250
metrics:
- date: "20260213"
count: 45
uniqueUsers: 22
- date: "20260214"
count: 78
uniqueUsers: 35
- bounds:
x: 400
y: 0
width: 400
height: 250
metrics:
- date: "20260213"
count: 22
uniqueUsers: 21
- date: "20260214"
count: 23
uniqueUsers: 22
belowThreshold:
summary: "Returned when the total number of unique clicks is below the privacy threshold"
value:
richMenuId: "richmenu-0123456789abcdef0123456789abcdef"
"400":
description: "Bad request. The `from` or `to` parameter is missing or invalid, or the aggregation period exceeds the allowed maximum."
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorResponse"
"404":
description: "Not found. The specified rich menu does not exist."
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorResponse"
components:
securitySchemes:
Bearer:
type: http
scheme: bearer
description: "Channel access token"
schemas:
GetFriendsDemographicsResponse:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-demographic
description: "Get friend demographics"
type: object
properties:
available:
type: boolean
description: "true if friend demographic information is available."
genders:
type: array
items:
$ref: "#/components/schemas/GenderTile"
description: "Percentage per gender."
ages:
type: array
items:
$ref: "#/components/schemas/AgeTile"
description: "Percentage per age group."
areas:
type: array
items:
$ref: "#/components/schemas/AreaTile"
description: "Percentage per area."
appTypes:
type: array
items:
$ref: "#/components/schemas/AppTypeTile"
description: "Percentage by OS."
subscriptionPeriods:
items:
$ref: "#/components/schemas/SubscriptionPeriodTile"
type: array
description: "Percentage per friendship duration."
GenderTile:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-demographic
type: object
properties:
gender:
type: string
enum:
- male
- female
- unknown
description: "users' gender"
percentage:
type: number
format: double
description: "Percentage"
AgeTile:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-demographic
type: object
properties:
age:
type: string
enum:
- from0to14
- from15to19
- from20to24
- from25to29
- from30to34
- from35to39
- from40to44
- from45to49
- from50
- from50to54
- from55to59
- from60to64
- from65to69
- from70
- unknown
description: "users' age"
percentage:
type: number
format: double
description: "Percentage"
AreaTile:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-demographic
type: object
properties:
area:
type: string
description: "users' country and region"
percentage:
type: number
format: double
description: "Percentage"
AppTypeTile:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-demographic
properties:
appType:
type: string
enum:
- ios
- android
- others
description: "users' OS"
percentage:
format: double
type: number
description: "Percentage"
type: object
SubscriptionPeriodTile:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-demographic
properties:
subscriptionPeriod:
type: string
description: "Subscription period. Possible values: `within7days`, `within90days`, `unknown` etc."
enum:
# Less than 7 days
- within7days
# Equal to or greater than 7 days but less than 30 days
- within30days
# Equal to or greater than 30 days but less than 90 days
- within90days
# Equal to or greater than 90 days but less than 180 days
- within180days
# Equal to or greater than 180 days but less than 365 days
- within365days
# Equal to or greater than 365 days
- over365days
# Unknown
- unknown
percentage:
format: double
type: number
description: "Percentage. Possible values: [0.0,100.0] e.g. 0, 2.9, 37.6."
type: object
GetNumberOfMessageDeliveriesResponse:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-number-of-delivery-messages
description: "Get number of message deliveries"
type: object
properties:
status:
type: string
enum:
- ready
- unready
- out_of_service
description: "Status of the counting process."
broadcast:
format: int64
type: integer
description: "Number of messages sent to all of this LINE Official Account's friends (broadcast messages)."
targeting:
format: int64
type: integer
description: "Number of messages sent to some of this LINE Official Account's friends, based on specific attributes (targeted messages)."
autoResponse:
format: int64
type: integer
description: "Number of auto-response messages sent."
welcomeResponse:
format: int64
type: integer
description: "Number of greeting messages sent."
chat:
format: int64
type: integer
description: "Number of messages sent from LINE Official Account Manager [Chat screen](https://www.linebiz.com/jp/manual/OfficialAccountManager/chats/) (only available in Japanese)."
apiBroadcast:
format: int64
type: integer
description: "Number of broadcast messages sent with the `Send broadcast message` Messaging API operation."
apiPush:
format: int64
type: integer
description: "Number of push messages sent with the `Send push message` Messaging API operation."
apiMulticast:
format: int64
type: integer
description: "Number of multicast messages sent with the `Send multicast message` Messaging API operation."
apiNarrowcast:
format: int64
type: integer
description: "Number of narrowcast messages sent with the `Send narrowcast message` Messaging API operation."
apiReply:
format: int64
type: integer
description: "Number of replies sent with the `Send reply message` Messaging API operation."
GetNumberOfFollowersResponse:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-number-of-followers
description: "Get number of followers"
type: object
properties:
status:
description: "Calculation status."
type: string
enum:
- ready
- unready
- out_of_service
followers:
type: integer
format: int64
description: |+
The number of times, as of the specified date, that a user added this LINE Official Account as a friend for the first time.
The number doesn't decrease even if a user later blocks the account or when they delete their LINE account.
targetedReaches:
format: int64
type: integer
description: |+
The number of users, as of the specified date, that the LINE Official Account can reach through targeted messages based on gender, age, and/or region.
This number only includes users who are active on LINE or LINE services and whose demographics have a high level of certainty.
blocks:
type: integer
format: int64
description: |+
The number of users blocking the account as of the specified date.
The number decreases when a user unblocks the account.
GetMessageEventResponse:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-insight-message-event-response
description: "Statistics about how users interact with narrowcast messages or broadcast messages sent from your LINE Official Account."
properties:
overview:
$ref: "#/components/schemas/GetMessageEventResponseOverview"
messages:
description: "Array of information about individual message bubbles."
type: array
items:
$ref: "#/components/schemas/GetMessageEventResponseMessage"
clicks:
description: "Array of information about opened URLs in the message."
type: array
items:
$ref: "#/components/schemas/GetMessageEventResponseClick"
type: object
GetMessageEventResponseOverview:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-insight-message-event-response
description: "Summary of message statistics."
type: object
properties:
requestId:
type: string
description: "Request ID."
timestamp:
format: int64
type: integer
description: "UNIX timestamp for message delivery time in seconds."
delivered:
format: int64
type: integer
description: |+
Number of messages delivered.
This property shows values of less than 20.
However, if all messages have not been sent, it will be null.
uniqueImpression:
format: int64
type: integer
description: "Number of users who opened the message, meaning they displayed at least 1 bubble."
nullable: true
uniqueClick:
format: int64
type: integer
description: "Number of users who opened any URL in the message."
nullable: true
uniqueMediaPlayed:
format: int64
type: integer
description: "Number of users who started playing any video or audio in the message."
nullable: true
uniqueMediaPlayed100Percent:
format: int64
type: integer
description: "Number of users who played the entirety of any video or audio in the message."
nullable: true
GetMessageEventResponseMessage:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-insight-message-event-response
type: object
properties:
seq:
format: int32
type: integer
description: "Bubble's serial number."
impression:
format: int64
type: integer
description: "Number of times the bubble was displayed."
nullable: true
mediaPlayed:
format: int64
type: integer
description: "Number of times audio or video in the bubble started playing."
nullable: true
mediaPlayed25Percent:
format: int64
type: integer
description: "Number of times audio or video in the bubble started playing and was played 25% of the total time."
nullable: true
mediaPlayed50Percent:
format: int64
type: integer
description: "Number of times audio or video in the bubble started playing and was played 50% of the total time."
nullable: true
mediaPlayed75Percent:
format: int64
type: integer
description: "Number of times audio or video in the bubble started playing and was played 75% of the total time."
nullable: true
mediaPlayed100Percent:
format: int64
type: integer
description: "Number of times audio or video in the bubble started playing and was played 100% of the total time."
nullable: true
uniqueMediaPlayed:
format: int64
type: integer
description: "Number of users that started playing audio or video in the bubble."
nullable: true
uniqueMediaPlayed25Percent:
format: int64
type: integer
description: "Number of users that started playing audio or video in the bubble and played 25% of the total time."
nullable: true
uniqueMediaPlayed50Percent:
format: int64
type: integer
description: "Number of users that started playing audio or video in the bubble and played 50% of the total time."
nullable: true
uniqueMediaPlayed75Percent:
format: int64
type: integer
description: "Number of users that started playing audio or video in the bubble and played 75% of the total time."
nullable: true
uniqueMediaPlayed100Percent:
format: int64
type: integer
description: "Number of users that started playing audio or video in the bubble and played 100% of the total time."
nullable: true
GetMessageEventResponseClick:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-insight-message-event-response
type: object
properties:
seq:
type: integer
format: int32
description: "The URL's serial number."
url:
type: string
description: "URL."
click:
type: integer
format: int64
description: "Number of times the URL was opened."
nullable: true
uniqueClick:
type: integer
format: int64
description: "Number of users that opened the URL."
nullable: true
uniqueClickOfRequest:
type: integer
format: int64
description: "Number of users who opened this url through any link in the message. If a message contains two links to the same URL and a user opens both links, they're counted only once."
nullable: true
GetStatisticsPerUnitResponse:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-statistics-per-unit-response
description: "Response object for `get statistics per unit`"
type: object
properties:
overview:
$ref: "#/components/schemas/GetStatisticsPerUnitResponseOverview"
messages:
description: "Ar
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/line/refs/heads/main/openapi/line-insight-openapi.yml