Engagement API

​

개요

Enterprise

이 API는 관리형 액세스 레벨에서만 제공되는 엔터프라이즈 API입니다. 이 API를 사용하려면 먼저 엔터프라이즈 영업팀을 통해 계정을 개설해야 합니다. 자세히 알아보기

Engagement API는 게시물 노출 수 및 참여 지표에 대한 액세스를 제공합니다. 대부분의 지표와 엔드포인트는 OAuth 1.0a User Context를 사용해 인증해야 하지만, 공개 Favorite, Retweet, Reply, Video Views 지표에는 OAuth 2.0 Bearer Token과 /totals 엔드포인트를 사용해 액세스할 수 있습니다.  

참고: 일부 X 웹 대시보드에 보고되는 데이터와 Engagement API에 보고되는 데이터 사이에 차이가 있을 수 있습니다. 이러한 차이는 웹 대시보드가 일반적으로 선택한 기간 내에 발생한 참여 및/또는 노출 수만 표시하기 때문에 발생합니다. 예를 들어, 웹 대시보드는 달력상 한 달 동안의 게시물 참여만 표시할 수 있지만, Engagement API는 요청한 시간 범위 안에 속하는 한 해당 달의 범위를 넘어서는 참여까지도 표시할 수 있습니다. 이러한 경우에는 Engagement API를 정식 데이터 소스로 간주해야 합니다.  

​

요청 엔드포인트

Engagement API에는 세 가지 엔드포인트가 있습니다:

​

현재 합계: [/totals]

• 요청 시 원하는 포스트에 대해 노출수(Impressions) 합계 메트릭과 참여수(Engagements) 합계 메트릭을 반환합니다
• 다음 메트릭으로 제한됩니다: Impressions, Engagements, Favorites, Replies, Retweets, Quote Tweets, Video Views
• OAuth 1.0a User Context를 사용하여 최근 90일 이내에 생성된 포스트에 대한 Impressions 및 Engagements 메트릭을 조회할 수 있습니다
• OAuth 2.0 Bearer 토큰을 사용하여 모든 포스트에 대한 Favorites, Retweets, Quote Tweets, Replies 및 Video Views 메트릭을 조회할 수 있습니다
• 결과는 요청이 수행되는 시점의 노출수와 참여수 현재 합계를 기준으로 합니다
• 대시보드 보고서를 구성하고 여러 @handle 전반에 걸쳐 참여율을 계산하는 데 적합합니다
• 요청 한 번당 최대 250개 포스트에 대한 메트릭 조회를 지원합니다  

​

지난 28시간: [/28hr]

• 요청 시 지난 28시간 동안 발생한 노출 수 총합 지표, 참여 수 총합 지표, 그리고 개별 참여 지표의 상세 내역을 반환할 수 있습니다.
• 데이터는 Post ID별로, 그리고 시계열(일별 또는 시간별) 집계로 그룹화할 수 있습니다.
• 최근에 생성된 콘텐츠의 성과를 추적하는 데 적합합니다.
• 사용 가능한 모든 지표를 지원합니다.
• 요청당 최대 25개의 포스트에 대한 지표 요청을 지원합니다.  

​

Historical: [/historical]

• 요청은 최근 1년 동안의 노출 수(impressions), 참여 수(engagements), 그리고 개별 참여 지표의 세부 분류 데이터를, 게시물 생성 시간이 아닌 참여(engagement) 발생 시간을 기준으로 반환할 수 있습니다.
• 요청은 시작일과 종료일 파라미터를 지원하므로, 최장 4주까지의 특정 기간으로 범위를 좁힐 수 있는 유연성을 제공합니다.
• 게시물 참여 데이터는 과거 365일까지만 제공됩니다.
• 데이터는 게시물 ID별로, 그리고 시계열 기준으로는 집계 단위(일 또는 시간)별로 그룹화할 수 있습니다.
• 최근 성과를 과거 벤치마크와 비교 평가하거나, 특정 @handle의 과거 성과 추이를 파악하는 데 적합합니다.
• 사용 가능한 모든 지표를 지원합니다.
• 요청당 최대 25개의 포스트에 대한 지표 요청을 지원합니다.

​

사용 가능한 메트릭

아래 표에서는 Engagement API를 통해 조회할 수 있는 메트릭 type을 설명합니다.

아래 메트릭에 대해 더 자세히 알아보려면 메트릭 해석 방법 페이지를 확인하세요.

지표	엔드포인트 가용성	사용자 컨텍스트 필요	설명
impressions	전체	예	게시물이 조회된 총 횟수입니다. 이 지표는 지난 90일 이내에 게시된 게시물에만 제공됩니다.
engagements	전체	예	사용자가 게시물과 상호작용한 총 횟수입니다. 이 지표는 지난 90일 이내에 게시된 게시물에만 제공됩니다.
favorites	전체	예 - /28hrs & /Historical 아니요 - /totals	게시물이 즐겨찾기된 총 횟수입니다.
retweets	전체	예 - /28hrs 및 /Historical 아니요 - /totals	게시물이 리트윗된 총 횟수입니다.
quote_tweets	/totals	아니요 - /totals	게시물이 인용(Quote) 리트윗된 총 횟수입니다.
replies	전체	예 - /28hrs & /Historical 아니요 - /totals	게시물에 답글이 달린 총 횟수입니다.
video_views	전체	예 - /28hrs & /Historical 아니요 - /totals	특정 게시물에 포함된 동영상이 최소 2초 동안 화면에서 50% 이상 보인 횟수입니다. 동영상 조회수는 생성된 지 1800일 이하인 게시물에 대해서만 제공됩니다. 1800일보다 오래된 게시물에 대해 동영상 조회수를 요청하면, 응답에는 요청한 다른 지표를 담은 별도의 객체와 함께 다음 객체가 포함됩니다: “unsupported_for_video_views_tweet_ids”: [“TWEET_ID”] 주의: X가 소유·운영하는 플랫폼(모바일 App 및 웹사이트)에 표시되는 동영상 조회수 지표와 /28hr 및 /historical 엔드포인트를 통해 받는 수치 사이에는 차이가 발생할 수 있습니다. * X 사용자 인터페이스와 /totals 엔드포인트에 표시되는 동영상 조회수는, 해당 동영상이 게시된 모든 게시물을 기준으로 집계된 동영상 조회수를 나타냅니다. 즉, UI에 표시되는 이 지표에는 동영상이 리트윗되었거나 별도의 게시물로 재게시된 모든 경우의 조회수가 합산되어 포함됩니다. 이 지표에는 GIF의 동영상 조회수는 포함되지 않습니다. * /28hr 및 /historical 엔드포인트에서 제공되는 동영상 조회수는, 지표를 조회 중인 특정 게시물에서 발생한 조회수만을 포함합니다. 이 지표에도 GIF의 동영상 조회수는 포함되지 않습니다.
media_views	/28hr /historical	예	동영상, GIF, 이미지 등을 포함하여, 자동 재생되거나 사용자가 클릭해 미디어가 재생되거나 조회된 모든 횟수입니다.
media_engagements (이전 명칭: Media Clicks)	/28hr /historical	예	게시물에 포함된 이미지나 동영상 등의 미디어가 클릭된 총 횟수입니다.
url_clicks	/28hr /historical	예	게시물에 포함된 URL이 클릭된 총 횟수입니다.
hashtag_clicks	/28hr /historical	예	게시물에서 해시태그가 클릭된 횟수입니다.
detail_expands	/28hr /historical	예	게시물의 세부 정보를 더 보기 위해 게시물이 클릭된 횟수입니다.
permalink_clicks	/28hr /historical	예	게시물에 대한 퍼머링크(해당 게시물 전용 웹페이지)가 클릭된 횟수입니다.
app_install_attempts	/28hr /historical	예	게시물에서 앱 설치 이벤트가 발생한 횟수입니다.
app_opens	/28hr /historical	예	게시물에서 앱 열기 이벤트가 발생한 횟수입니다.
email_tweet	/28hr /historical	예	게시물이 이메일을 통해 공유된 횟수입니다.
user_follows	/28hr /historical	예	이 게시물을 통해 사용자(게시물 작성자)가 팔로우된 횟수입니다.
user_profile_clicks	/28hr /historical	예	이 게시물을 통해 사용자(게시물 작성자)의 프로필이 클릭된 횟수입니다.

​

참여 그룹화(Engagement groupings)

그룹화(grouping)를 사용하면 반환된 참여 지표를 원하는 방식으로 구성할 수 있습니다. 요청당 최대 3개의 그룹화를 포함할 수 있습니다. 아래 값 중 하나 이상을 기준으로 지표를 그룹화할 수 있습니다:

다음 세 엔드포인트 모두에서 지원됩니다:

• tweet.id
• engagement.type  

/28hr 및 /historical 엔드포인트는 시계열 지표를 제공할 수 있으므로, 다음도 지원합니다:

• engagement.day
• engagement.hour

그룹화에 대해 더 자세히 알아보려면 Guides 섹션의 Engagement API Grouping 페이지를 참조하세요.

​

가이드

​

개발자 시작하기 가이드

​

소개

이 문서의 목적은 개발자에게 Engagement API 연동에 대한 소개를 제공하는 것입니다. 먼저 연동의 ‘이유(why)’를 살펴보고, 이어서 연동의 ‘방법(how)’에 대한 기술적인 세부 사항을 살펴보겠습니다.

Engagement API는 무엇을 제공하나요?

• Engagement API는 3-legged OAuth를 사용해 해당 계정이 귀하의 App이 자신을 대신해 메트릭을 요청하도록 승인했다는 전제하에, 지난 90일 동안 특정 X 계정이 소유한 포스트에 대한 노출 수와 참여 데이터를 제공합니다. 이 강력하면서도 구현이 쉬운 솔루션을 통해 노출 수는 물론 URL 클릭, #해시태그 클릭 등 다양한 심층 참여 지표에 즉시 접근할 수 있습니다.
• Engagement API는 모든 게시물에 대해 좋아요, Retweets, Quote Tweets, 답글, 동영상 조회수의 총 집계 메트릭을 제공합니다. 이를 통해 개별 게시물 또는 포스트 모음에 대한 기본적인 참여 데이터를 효과적으로 수집할 수 있습니다.
• Engagement API는 15개 이상의 성과 메트릭을 사용해 콘텐츠 성과를 효과적으로 측정함으로써, 소셜 리스닝, 마케팅, 퍼블리싱 플랫폼이 X에서의 ROI를 측정할 수 있도록 새로운 가치를 제공합니다.
• Engagement API는 요청/응답 API로서, 앱 개발자가 게시물 id, 원하는 메트릭, 그리고 기간을 지정해 요청을 보내면 API가 해당 데이터를 즉시 반환할 수 있게 해줍니다.  

왜 통합해야 하나요? 예시 사용 사례

• 내 콘텐츠의 전체 도달 범위를 파악해 얼마나 많은 사람이 보는지 이해합니다. 얼마나 많은 사람이 동영상을 시청하고, 링크를 클릭하고, 해시태그를 클릭하며, 내 앱을 설치하는지 확인합니다.
• 전체 및 시계열 기반 참여 지표를 생성합니다.
• 모든 공개 게시물에 대해 기본적인 참여 지표(즐겨찾기, 리트윗, 인용 Tweet, 답글)를 파악합니다.
• 이러한 지표를 활용해 어떤 유형의 게시물이 효과적인지 판단하고, 그런 게시물을 더 자주 올려 콘텐츠의 노출과 참여를 더 많이 얻습니다.
• 내 게시물 중 하나가 ‘좋아요’ 100개 또는 다른 임계값에 도달할 때마다(예: 다른 소유 계정의 콘텐츠를 리트윗하는 등) 마케팅 작업을 자동화합니다.
• A/B 테스트 도구로 활용하기 위해 캠페인 간 성과를 비교·벤치마킹합니다.
• 고객 지원 부서에 어떤 유형의 콘텐츠가 반응을 이끌어내는지 분석하여, 어떻게 그리고 언제 응답할지 결정합니다.
• 내 플랫폼에서 게시된 콘텐츠에 대한 분석을 표시합니다.  

Engagement API는 2016년에 출시되었으며, 이러한 심층적인 참여 지표를 대규모로 제공한 최초의 X API였습니다. Engagement API는 사용하기 쉽고, 고객이 이 프로세스를 자동화할 수 있도록 해줍니다. 다음은 예시 통합을 설명하는 사례 연구입니다.

• 적십자와 함께 캠페인 성공 측정하기

이제 Engagement API의 ‘이유’를 살펴보았으니, 기술 세부 사항을 알아보겠습니다.

​

Engagement API 연동

API 소개

Engagement API는 JSON으로 인코딩된 요청을 수신하고 JSON으로 인코딩된 참여(engagement) 메트릭으로 응답하는 간단한 RESTful API입니다. 요청은 세 가지 주요 부분으로 구성됩니다(자세한 내용은 링크를 참고하세요).

• Post ID 배열
• 관심 있는 metric types를 지정하는 배열. type에는 impressions, retweets, hashtag_clicks, user_follows 등이 포함됩니다.
• API 응답에서 참여 데이터가 어떻게 구성되기를 원하는지 나타내는 JSON 구조인 Engagement groupings.

많은 상황에서 Engagement Types와 Groupings은 요청마다 비교적 일정하게 유지되고, Post ID만 변경됩니다.

Engagement API는 세 개의 endpoint를 제공합니다.

• Totals - 포스트에 대한 참여 총합을 제공합니다. 일부 메트릭은 모든 포스트에 대해 사용 가능하지만, 다른 메트릭은 최근 90일에 대해서만 사용 가능합니다.
• 28 hour - 최근 28시간 동안의 시계열 참여 메트릭을 제공합니다.
• Historical - 2014년 9월 1일 이후에 게시된 포스트에 대해, 최대 연속 4주 동안의 시계열 참여 메트릭을 제공합니다.

/totals endpoint는 한 번의 요청에서 최대 포스트 250개에 대한 메트릭 요청을 지원합니다. /28hour 및 /historical endpoint는 요청당 25개를 지원합니다.

Engagement API에 대한 액세스 권한을 얻는 방법을 살펴본 후, API 요청을 수행하는 절차를 단계별로 설명하고, OAuth 개요를 제공하며, 기타 기술 리소스에 대한 링크를 안내합니다.

API 액세스 권한 받기

이 문서를 읽고 있다면 이미 Engagement API 액세스 권한을 부여받았을 가능성이 높습니다. 그렇지 않다면 Enterprise 계정 관리자에게 문의하거나 여기에서 Enterprise 액세스를 신청하세요.

첫 번째 단계는 승인된 개발자 계정을 통해 Developer Console에서 X App을 생성하는 것입니다. 계정 관리자는 액세스를 제공하기 위해 이 애플리케이션과 연결된 숫자형 App ID가 필요합니다. 개발자 계정을 신청해야 하는 경우 여기에서 신청할 수 있습니다.

요청 보내기

다행인 것은 Engagement API에 요청을 보내는 일이 간단하다는 점입니다. 이 예제에서는 다음 두 개의 @XDevelopers 포스트에 대해, 총 Retweets, Quote Tweets, Favorites, 그리고 replies 수를 요청해 보겠습니다:

1/ Today we’re sharing our vision for the future of the X API platform

— Twitter Dev (@TwitterDev) April 6, 2017

Don’t miss the Posts about your Post.

Now on iOS, you can see Retweets with comments all in one place. pic.x.com/oanjZfzC6y

— X (@X) May 12, 2020

첫 번째 단계는 JSON 형식의 API 요청을 구성하는 것입니다. 여기에는 배열로 담긴 두 개의 게시물 id, 관심 있는 참여 유형 배열, 그리고 응답에서 지표를 어떻게 구성해 제공받을지를 나타내는, 사용자 정의 이름의 “groupings” JSON 객체가 포함됩니다. 이 요청은 다음과 같은 형태가 됩니다:

{
  "tweet_ids": [
    1260294888811347969, 850006245121695744
  ],
  "engagement_types": [
    "retweets", "quote_tweets", "favorites", "replies"
  ],
  "groupings": {
    "engagement-types-by-id": {
      "group_by": [
        "Tweet.id", "engagement.type"
      ]
    }
  }
}

이러한 총합 지표를 조회하기 위해 https://data-api.x.com/insights/engagement/totals 엔드포인트에 이 JSON 요청을 POST합니다.

요청 본문이 JSON으로 인코딩되었고 gzip으로 압축되었음을 나타내기 위해 다음 헤더를 포함합니다(요청 본문이 매우 커질 수 있습니다).

• Content-Type: application/json
• Accept-Encoding: gzip  

요청을 보낼 때는 OAuth를 사용해 인증하며, 이에 대해서는 다음 섹션에서 더 자세히 설명합니다.

API는 다음과 같은 페이로드를 반환합니다.

{
  "grouping name": {
    "1260294888811347969": {
      "favorites": "17111",
      "quote_tweets": "3254",
      "replies": "1828",
      "retweets": "5218"
    },
    "850006245121695744": {
      "favorites": "492",
      "quote_tweets": "66",
      "replies": "42",
      "retweets": "324"
    }
  }
}

응답에는 “groupings” 정의에서 설명한 구조로 요청한 메트릭이 포함되어 있으며, 먼저 게시물 ID별로, 그다음 단계에서 참여 type별로 메트릭이 나열된다는 점에 유의하세요.

꽤 간단했습니다. OAuth 인증이 처음이라면 다음 섹션을 확인해 보세요.

​

OAuth로 인증하기

OAuth는 기술 업계에서 매우 널리 사용되는 인증 표준입니다. 이미 OAuth(아마도 다른 X API와 함께)를 사용하고 있다면, 아마도 언어별 OAuth 패키지를 사용해 복잡한 세부 사항을 추상화하고 있을 것입니다. OAuth가 처음이라면, OAuth with the X API 페이지를 방문하거나 https://oauth.net으로 바로 이동해 더 자세히 알아보시기 바랍니다. 그런 다음, 통합에 사용할 프로그래밍 언어에 맞는 OAuth 패키지를 찾아서 시작할 것을 권장합니다. 이러한 패키지를 사용하면, 일반적으로 인증 과정은 키와 토큰을 설정하고, HTTP 객체(예: 클라이언트)를 만든 다음, 그 객체를 사용해 요청을 보내는 방식으로 이루어집니다.

예를 들어, Ruby 생태계에서는 아래의 의사 코드가 Ruby gem ‘oauth’를 사용해 OAuth를 지원하는 App을 만들고 POST 요청을 보내는 방법을 보여줍니다.

require 'oauth'

#Assemble JSON request (as above).
request = make_json_request()

#Build an app consumer object with my app consumer key and secret.
consumer = OAuth::Consumer.new(keys['consumer_key'], keys['consumer_secret'], {:site => ‘https://data-api.x.com’})
#권한을 제공하는 계정에서 제공한 토큰으로 사용자 토큰 빌드. 앱 전용 요청을 하는 경우 #(권한이 필요하지 않은 Tweet을 /totals 엔드포인트로 확인), 이 단계는 건너뛸 수 #있습니다.
token = {:oauth_token => keys['access_token'], :oauth_token_secret => keys['access_token_secret']}

#Create oauth-enabled app object.
app = OAuth::AccessToken.from_hash(consumer, token)
#Make POST request.
result = app.post(“/insights/engagement/totals", request, {"content-type" => "application/json", "Accept-Encoding" => "gzip"})

Engagement API는 애플리케이션 전용 인증과 사용자 컨텍스트 인증을 모두 지원합니다. /totals 엔드포인트로 소유하지 않은 공개 포스트에 대한 참여 지표를 수집하는 경우에는 사용자 권한이 필요하지 않으므로 애플리케이션 전용 인증을 사용할 수 있습니다. 이 경우에는 앱 키와 시크릿만 사용해 인증합니다.

OAuth는 또한 앱이 사용자와 연관된 토큰을 사용하여 “다른 사용자를 대신해” API 요청을 수행할 수 있도록 허용합니다. 소유한 포스트, 즉 사용자 토큰을 보유하고 있는 사용자가 게시한 포스트에 대한 Engagement 지표를 생성하는 경우에는 사용자 컨텍스트에서 요청을 보내게 되며, 이는 앱 키와 사용자별 액세스 토큰을 모두 사용해 인증한다는 뜻입니다. 이러한 사용자 액세스 토큰은 일반적으로 ‘Sign-in with X’ 프로세스를 통해 제공되거나 사용자로부터 직접 획득합니다(토큰을 사용자로부터 직접 획득하는 경우에는 반드시 twurl을 사용해야 합니다). 사용자가 토큰을 제공한 이후에는 토큰이 만료되지 않으며, 사용자가 토큰을 재설정하거나 비밀번호를 변경하지 않는 한 Engagement API에서 해당 사용자를 대신해 요청을 보내는 데 계속 사용할 수 있습니다. 이러한 경우에는 사용자가 새 토큰을 다시 제공해야 합니다.

어떤 지표에 어떤 인증이 필요한지는 이 표를 통해 확인할 수 있습니다.

​

Engagement API 엔드포인트 선택하기

Engagement API는 다음과 같은 세 가지 서로 다른 엔드포인트를 제공합니다:

• Totals - ‘owned’ 또는 ‘unowned’ 포스트에서 선택된 지표의 총계를 제공합니다. 일부 지표는 모든 포스트에 대해 제공되지만, 다른 지표는 최근 90일 이내에 게시된 포스트에 대해서만 제공됩니다. 요청당 최대 250개의 포스트를 지원합니다.
• 28 hour - 최근 28시간 동안의 ‘owned’ 포스트에 대한 시계열 Engagement 지표를 제공합니다. 요청당 최대 25개의 포스트를 지원합니다.
• Historical - 2014년 9월 1일 이후에 게시된 ‘owned’ 포스트에 대해, 최대 4주 연속 기간에 대한 시계열 Engagement 지표를 제공합니다. 요청당 최대 25개의 포스트를 지원합니다.  

각 엔드포인트는 고유한 특성을 가지고 있습니다. 세 가지를 모두 사용할 계획이든, 아니면 어떤 것이 사용 중인 유스 케이스에 가장 잘 맞는지 결정하려는 중이든, 이들 간의 차이를 이해하는 것이 중요합니다.

아래에서는 몇 가지 핵심 개념을 소개하고, 세 가지 엔드포인트를 더 자세히 살펴본 뒤, 일반적으로 특정 엔드포인트에 매핑되는 예시 유스 케이스를 제시합니다. 이 정보가 세 가지 엔드포인트를 더 효율적으로 통합하거나, 단일 엔드포인트 중에서 목적에 가장 잘 맞는 것을 선택하는 데 도움이 되기를 바랍니다.  

​

핵심 개념

세 가지 Engagement API 엔드포인트가 제공하는 기능과 데이터의 차이를 이해하는 데 도움이 되는 몇 가지 핵심 개념이 있습니다.  

노출 및 참여 지표

노출 수(impressions)는 특정 게시물이 X 플랫폼에서 자연(organic) 환경에서 조회된 횟수를 나타냅니다. 프로모션 또는 유료(Paid) 환경에서 노출된 게시물로부터 발생한 노출 수는 포함되지 않습니다. Engagement API 이전에는 게시물 노출 수는 잠재적인 조회수만을 나타내는 지표였습니다. 이는 작성자의 계정 팔로워 수와 해당 콘텐츠를 리트윗한 계정의 팔로워 수를 합산하는 방식에 기반했으며, 특정 사용자가 실제로 그 게시물을 보지 못하는 흔한 상황은 반영하지 못했습니다.

Engagement API가 생성하는 노출 지표는 게시물이 실제로 화면에 렌더링되어 표시된 횟수를 측정한 실제 측정값입니다. 사용자가 귀하의 계정을 팔로우하고 있더라도 그 사용자가 해당 게시물을 보지 못했다면, 이는 노출 수로 계산되지 않습니다.

Engagement API는 게시물이 노출되었을 때 사용자가 취할 수 있는 개별 행동을 나타내는 14개의 고유한 참여 지표 유형을 제공합니다. 여기에는 리트윗하기, 좋아요 누르기, 답글 달기, #해시태그·링크·미디어와 같은 엔티티를 클릭하기, 작성자를 팔로우하기, 작성자 프로필 보기 등이 포함됩니다. 이러한 개별 행동은 모두 단일 Engagements 지표로 집계됩니다.

소유 및 비소유 X 콘텐츠

Engagement API는 소유 포스트와 비소유 포스트를 명확히 구분합니다. 소유 포스트는 내 계정에서 작성된 포스트이거나, 해당 포스트에 대한 Engagement 데이터를 요청할 수 있는 권한을 획득한 포스트를 의미합니다. 다른 X API와 마찬가지로, 다른 X 사용자/계정이 대신해서 API 요청을 할 수 있도록 허용하는 액세스 토큰을 공유하도록 함으로써 권한을 얻게 됩니다. 이러한 토큰을 획득하는 일반적인 방법은 ‘Sign in with X’ 프로세스를 사용하는 것입니다.

/totals 엔드포인트는 소유 및 비소유 포스트 모두에 대한 Engagement 데이터를 제공합니다. 비소유 포스트의 경우, 포스트 화면에 공개적으로 표시되는 Favorite, Retweet, Reply와 같은 Engagement 지표를 요청할 수 있습니다. 이러한 지표와 관련해 Engagement API가 제공하는 가치는, 이 지표들을 자동화된 방식으로 대규모로 조회할 수 있는 기능입니다. 소유 포스트의 경우 /totals 엔드포인트는 Impression과 (총) Engagement 지표도 함께 제공합니다.

/28hr 및 /historical 엔드포인트는 소유 포스트에 대한 지표만 제공하며, 이는 이 엔드포인트들에 요청을 보낼 때 사용자 컨텍스트를 함께 전달해야 함을 의미합니다.

총합 및 시계열 참여 데이터

/totals 엔드포인트는 이름에서 알 수 있듯이 참여 유형별 총합만 제공합니다. 이 수치는 게시물이 게시된 이후 현재까지의 최신 총합을 나타냅니다. 게시물이 막 게시된 직후에 해당 게시물의 지표를 반복해서 요청하면, 일반적으로 요청할 때마다 이 총합 값이 변경됩니다.

/28hr 및 /historical 엔드포인트는 총합과 시계열 데이터를 모두 제공할 수 있습니다. 시계열 데이터를 요청할 때는 참여 지표를 일별 또는 시간별 데이터로 집계할 수 있습니다.   

/28hr 및 /historical 엔드포인트로 시계열 데이터를 요청하는 방법은 참여 그룹화 문서를 참고하세요.

​

엔드포인트 및 예시 사용 사례

위에서 설명한 특성과 차이점을 바탕으로, 각 개별 엔드포인트는 일반적으로 서로 다른 유형의 사용 사례에 매핑됩니다. 특정 사용 사례에 가장 적합한 엔드포인트를 선택할 수 있도록, 아래에 몇 가지 사용자 요청 예시와 이를 가장 잘 만족하는 엔드포인트를 제시합니다.

/totals

• 일부 메트릭 type(Impressions, Engagements, Favorites, Retweets, Quote Tweets, Replies, Video Views)에만 액세스하면 된다.
• 소유한 포스트뿐만 아니라 모든 포스트에 대해 기본 참여 데이터를 조회해야 한다.
• 경쟁사와 성과를 비교하고 싶다.
• 내가 소유하지 않은 포스트를 포함하는 해시태그나 캠페인의 기본 참여 통계를 추적하고 싶다.
• 일별이나 시간별로 분리된 데이터는 필요 없고, 요청 시점의 현재 합계만 필요하다.
• 보고서나 대시보드에 표시할 단일 메트릭만 필요하고, 데이터를 별도로 저장하고 싶지 않다.
• 페이지 로드 시점에 데이터를 표시하고 싶으며, 요청 한 번으로 응답만 받으면 된다.
• 하루에 수십만 혹은 수백만 개의 포스트에 대한 데이터를 조회해야 한다.  

/28hr

• 모든 17가지 metric type에 대한 액세스가 필요합니다.
• 지난 28시간 동안 게시된 최신 포스트의 데이터를 보고 싶습니다.
• 하루에 한 번 제가 필요한 데이터를 가져오는 작업이 있어서, 전날 하루치 데이터만 가져오면 됩니다.
• 일(day) 또는 시간(hour) 단위로 세분화된 metric이 필요합니다.
• 대시보드에서 시간(hour) 단위로 활동 시계열 분포를 보여주고 싶습니다.
• 하루에 수십만 개 포스트에 대해 고용량 액세스가 필요합니다.
• 저장소 용량이 있어서 데이터를 하루에 한 번 갱신하고 누적 집계를 유지할 수 있습니다.  

/historical

• 17개 메트릭 type 전체에 대한 접근 권한이 필요합니다.
• 2014년 9월까지 거슬러 올라가는 포스트 생성 과거 데이터를 조회해야 합니다.
• 캠페인을 비교하는 상세한 과거 분석을 보여주고 싶습니다.
• 메트릭이 일 단위 또는 시간 단위로 세분화되어야 합니다.
• Engagement API에 대한 높은 수준의 접근 권한은 필요 없으며, 하루에 수백 개 또는 수천 개의 포스트 데이터만 조회하면 됩니다.

​

Engagement API의 주요 특성

• JSON 데이터를 제공하는 RESTful API로, JSON 본문을 가진 POST 요청을 지원합니다.
• 요청 유형: 클라이언트 App은 다음과 같은 유형의 요청을 보낼 수 있습니다.
  • 총 참여 수 조회 — /totals 엔드포인트로의 HTTP POST 요청
  • 최근 28시간 참여 수 조회 — /28hr 엔드포인트로의 HTTP POST 요청
  • 히스토리컬(과거) 참여 수 조회 — /historical 엔드포인트로의 HTTP POST 요청
• OAuth 인증:
  • OAuth 1.0 사용자 컨텍스트: 사용자가 3-legged OAuth를 통해 귀하의 App을 승인한 경우, 해당 사용자가 소유한 게시물에 대해 제공되는 모든 메트릭을 조회할 수 있습니다. 요청을 보낼 때는 해당 사용자의 Access Token을 사용해야 합니다.
  • OAuth 2.0 Bearer 토큰: 선택된 메트릭(리트윗, 인용 Tweet, 답글, 즐겨찾기, 동영상 조회수)은 모든 공개 게시물에 대해 사용할 수 있습니다. 
• 요청 메타데이터 및 구조: 요청 데이터는 게시물 id 배열, 참여 유형 배열, 참여 그룹화 구조로 구성된 JSON 객체입니다.
• 요청당 게시물 수:
  • /totals 엔드포인트: 게시물 id 250개
  • /28hr 엔드포인트: 게시물 id 25개
  • /historical 엔드포인트: 게시물 id 25개
• 참여 메트릭 가용성:
  • /totals — 게시물이 게시된 시점부터의 메트릭 총합입니다. 노출수(Impressions)와 참여수(Engagements)는 최근 90일 이내에 게시된 게시물에 대해서만 제공되며, 리트윗, 인용 Tweet, 답글, 즐겨찾기, 동영상 조회수는 모든 포스트에 대해 제공됩니다.
  • /28hr — 요청 시점으로부터 직전 28시간입니다.
  • /historical — 2014년 9월 1일부터 시작하는 임의의 28일 기간입니다.
• 메트릭 유형: 각 요청에는 Metric Types 배열이 포함됩니다. 가용성은 엔드포인트에 따라 다르며, /totals 엔드포인트에서 요청하는 경우에는 게시물이 사용자 권한 기반인지 여부에 따라 달라집니다.
  • /totals 엔드포인트:
    • 모든 포스트: 즐겨찾기, 리트윗, 인용 Tweet, 답글, 동영상 조회수
    • OAuth 1.0a 사용자 컨텍스트 필요: 노출수(Impressions), 참여수(Engagements), 즐겨찾기, 답글, 리트윗
  • /28hr 및 /historical 엔드포인트 (게시물 소유자의 Access Token을 사용하는 OAuth 1.0a 사용자 컨텍스트 필요): 노출수(Impressions), 참여수(Engagements), 즐겨찾기, 답글, 리트윗, URL 클릭, 해시태그 클릭, 상세 보기 클릭, 퍼머링크 클릭, 미디어 클릭, App 설치 시도, App 열기, 게시물 이메일, 동영상 조회수, 미디어 조회수
• 참여 그룹화(Engagement groupings): 각 요청에는 Engagement Groupings 배열이 포함됩니다. 이 그룹화를 사용하면 반환되는 메트릭의 구성 방식을 사용자 정의할 수 있습니다. 요청 하나당 최대 세 개의 그룹화를 포함할 수 있습니다. 메트릭은 다음 값 기준으로 구성할 수 있습니다.
  • 모든 엔드포인트: 게시물 id, 참여 유형
  • /28hr 및 /historical 엔드포인트: 다음 추가 그룹화를 지정하면 시계열 데이터(time-series)를 제공합니다: 참여 일자, 참여 시간
• 통합 시 기대 사항: 귀하의 팀은 다음 항목에 대한 책임을 집니다.
  • Engagement API에 HTTP 요청을 보내고, 요청에 포함된 게시물 id에 대한 참여 메트릭을 반환할 수 있는 클라이언트 App을 생성 및 유지 관리합니다.
• 제한 사항
• 동영상 조회수는 게시된 지 1,800일 이하인 포스트에 대해서만 제공됩니다.

​

Engagement API 인증

유의 사항: 

Engagement API를 사용하기 전에 X에서 개발자 App에 대해 Engagement API 접근 권한을 활성화해야 합니다. 이를 위해 인증에 사용할 App ID를 계정 관리자 또는 기술 지원 팀과 반드시 공유해 주십시오.

Engagement API에는 두 가지 인증 방법이 있습니다: OAuth 1.0a와 OAuth 2.0 Bearer Token입니다. 

OAuth 2.0 Bearer Token(“애플리케이션 전용(application-only)”이라고도 함)을 사용하면 공개로 제공되는 참여(engagement) 지표에 액세스할 수 있습니다. 이 인증 방식은 /totals 엔드포인트에 요청을 보낼 때, 공개적으로 이용 가능한 포스트에 대해 Favorites(즉, Likes), Retweets, Quote Tweets, Replies 및 동영상 조회수의 총합을 가져오는 데 사용할 수 있습니다. 

OAuth 1.0a(“사용자 컨텍스트(user context)”라고도 함)를 사용하면 사용자를 대신하여 요청을 보내고, 해당 사용자에게 속한 비공개 참여 지표에 액세스할 수 있습니다. 

이 인증 방식은 다음과 같은 경우에 필요합니다:

• /28hr 엔드포인트 및 /historical 엔드포인트로 전송되는 모든 요청
• 다음과 같은 비공개 지표에 액세스하는 모든 경우: Impressions, Engagements, Media Views, Media Engagements, URL Clicks, Hashtag Clicks, Detail Expands, Permalink Clicks, App Install Attempts, App Opens, Email Post, User Follows, User Profile Clicks

OAuth 1.0a로 요청을 보낼 때는, 관심 있는 포스트 또는 보호된 리소스를 소유한 사용자의 Access Tokens(Access Token과 Secret)를 포함해야 합니다. 보호된 사용자 데이터를 요청할 때 올바른 사용자 Access Tokens를 제공하지 않으면 Engagement API는 403 Forbidden 오류를 반환합니다.

Engagement API는, 해당 포스트의 소유 사용자를 대신하여 인증하더라도 보호된 포스트의 참여 데이터를 가져오는 것을 허용하지 않습니다. 이렇게 시도하면 "Tweet ID(s) are unavailable"라는 메시지와 함께 400 Bad Request 오류가 반환됩니다.

자신의 X 계정(즉, 개발자 App을 소유한 계정)을 대신하여 요청을 보내는 경우, 개발자 콘솔의 해당 개발자 App에 대한 “Keys and tokens” 탭에서 필요한 Access Tokens를 직접 생성할 수 있습니다.

다른 사용자를 대신하여 요청을 보내는 경우, 필요한 Access Tokens를 얻기 위해 3-legged OAuth 플로우를 사용해야 합니다. 이 작업 방법에 대한 자세한 내용은 다음 문서를 참고하십시오: OAuth 1.0a: how to obtain a user’s access tokens.

추가 예제(여기에는 OAuth 1.0a를 사용한 인증 방법도 포함됨)를 보려면, XDevelopers의 Engagement API용 Python 샘플 코드를 확인하십시오.

​

Engagement API의 최신 변경 사항

Engagement API는 X에서의 활동 성과를 모니터링할 수 있도록, 매우 중요한 노출 및 참여(engagement) 지표를 제공합니다. 당사 데이터에 기반한 마케팅 의사결정을 지원하기 위한 지속적인 노력의 일환으로, X 전반의 지표 간 일관성을 더욱 높이기 위한 Engagement API의 최신 변경 사항을 소개합니다.  

최근 Engagement API를 업데이트하여 X 애널리틱스 대시보드(analytics.x.com)에서 사용하는 것과 동일한 지표 집계 방법론을 사용하도록 변경했습니다. 새로운 지표를 도입하면서 API의 호환성을 최대한 해치지 않도록 신중하게 접근했으며, 첫 번째 변경 사항 세트는 2017년 10월 9일에 배포했습니다. 이 변경을 통해 여러분이나 고객이 X에서 성과를 모니터링하는 모든 채널에서 일관성이 향상됩니다. 아래에서 변경 사항의 세부 개요를 확인하십시오:

Metric	Change
engagements	전체 engagements에 포함되는 세부 지표를 업데이트하여 Post 분석 대시보드와의 일관성을 맞췄습니다. Engagements는 “사람들이 이 게시물과 상호작용한 횟수(times people interacted with this Post)”를 측정합니다. 동영상 또는 GIF와 같은 미디어가 포함된 게시물의 경우, engagements 지표에는 더 이상 media views가 포함되지 않습니다. Media views는 이제 _media_views_라는 새로운 지표를 통해 확인할 수 있습니다.
media_clicks*	이 지표는 “media_engagements”라는 새로운 지표로 대체되었습니다.
video_views	2018년 7월 6일부터 이 지표는 /totals 엔드포인트를 통해 ‘unowned’ 포스트에도 사용할 수 있습니다. 이는 app-only 인증을 사용해 모든 포스트에 대한 동영상 조회 수에 접근할 수 있음을 의미합니다.  video views는 최대 1800일 이내의 게시물에 대해서만 요청할 수 있습니다. 1800일보다 오래된 게시물에 대해 video views를 요청하려고 하면 다음과 같은 응답을 받게 됩니다: “unsupported_for_video_views_tweet_ids”: [“TWEET_ID”] 주의: video_views는 동영상의 50% 이상이 최소 2초 동안 화면에 노출되어야 조회로 집계된다는 MRC 표준에 기반하기 때문에 media_views와 값이 다를 수 있습니다. 또한 X의 자체 플랫폼(모바일 App 및 웹사이트)에 표시되는 video views 지표와, /28hr 및 /historical 엔드포인트를 통해 받는 숫자 사이에 차이가 있을 수 있습니다. * X 사용자 인터페이스와 /totals 엔드포인트를 통해 제공되는 video views는 해당 동영상이 게시된 모든 포스트를 합산한 조회 수를 표시합니다. 즉, UI에 표시되는 지표는 해당 동영상이 리트윗되었거나 별도의 포스트로 재게시된 모든 경우의 조회 수를 합산한 값입니다. * /28hr 및 /historical 엔드포인트를 통해 제공되는 video views는 여러분이 지표를 조회하는 특정 포스트에서 발생한 조회 수만 포함합니다.
media_views	동영상, vine, gif, 이미지 전반에서 자동 재생 및 클릭을 포함한 모든 미디어 조회를 합산한 값입니다. 주의: 이미지가 포함된 게시물의 경우 analytics 대시보드에서는 media_views 지표가 표시되지 않지만, Engagement API에서는 해당 값이 반환됩니다.
media_engagements*	동영상, vine, gif, 이미지 전반에서 미디어에 대한 클릭 수를 포함합니다. 이 지표는 _media_clicks_를 대체합니다.
quote_tweets	2020년 7월 7일부터 이 지표는 /totals 엔드포인트를 통해 ‘unowned’ 포스트에도 사용할 수 있습니다. 이는 app-only 인증을 사용하여 모든 포스트에 대한 인용 게시물(Quote Post) 수에 접근할 수 있음을 의미합니다.

​

메트릭 해석하기

참고: 일부 X 웹 대시보드에 보고되는 데이터와 Engagement API에 보고되는 데이터 사이에 차이가 있을 수 있습니다. 이러한 차이는 웹 대시보드가 일반적으로 선택한 기간 내에 발생한 참여 및/또는 노출만 표시하기 때문에 발생합니다. 예를 들어, 웹 대시보드는 한 달(달력 기준) 동안의 포스트 참여만 표시할 수 있지만, Engagement API는 해당 달을 넘어가더라도 요청한 기간 내에 포함되는 모든 참여를 표시할 수 있습니다. 이러한 경우에는 Engagement API를 신뢰할 수 있는 기준(source of truth)이 되는 데이터 소스로 간주해야 합니다.  

​

노출수 및 참여 데이터

Engagement API는 자연 노출수 및 참여 데이터를 제공합니다.

노출수는 특정 게시물이 X 플랫폼에서 자연 노출 환경에서 조회된 횟수를 나타냅니다. 프로모션 또는 유료 환경에서 노출된 게시물로부터 발생한 노출수는 포함되지 않습니다.

참여는 특정 게시물이 조회자에 의해 자연 및 프로모션 환경 모두에서 상호작용이 발생한 횟수를 나타냅니다. 참여에는 리트윗, 즐겨찾기, 답글, URL 클릭, 해시태그 클릭, 멘션 클릭, 미디어 조회 등이 포함되지만 이에 제한되지는 않습니다. 포함되는 전체 참여 동작 목록은 Engagement Data 섹션을 참고하세요. 

기본적인 참여율을 계산하려면, 분석 중인 기간 동안 특정 게시물에 대해 총 참여 수를 총 노출수로 나누어 계산하세요.

노출수 및 참여 데이터는 소유한 @handle의 게시물 또는 귀하의 애플리케이션이 해당 게시물의 세부 정보를 조회할 수 있도록 승인한 @handle의 게시물에 대해서만 조회할 수 있습니다.  내부적으로 Engagement API는 계약된 @handle 한도 대비 요청된 고유 @handle 수를 추적합니다.  또한 클라이언트 측에서 한 달 동안 @handle 요청 사용량을 함께 추적하는 것을 권장합니다.  

​

비디오 지표

X 내에서 미디어 노출을 나타내는 서로 다른 지표가 몇 가지 있습니다. 첫 번째는 비디오 조회수(video views) 지표로, 최소 2초 동안 비디오의 50% 이상이 화면에 노출되어야 한다는 MRC 기준에 따릅니다. 두 번째는 Media Views로, 동영상, vine, gif, 이미지 전반에 걸쳐 집계된 미디어의 모든 조회수(자동 재생 및 클릭)를 포함합니다.

비디오 조회수 지표는 /28hour 및 /historical 엔드포인트를 통해 소유한 포스트에 대해 사용할 수 있으며, /totals 엔드포인트를 통해 소유하지 않은 모든 포스트에 대해서도 사용할 수 있습니다. 

X 사용자 인터페이스의 비디오 조회수 지표 역시 동일한 MRC 기준을 사용하지만, X가 소유·운영하는 플랫폼(모바일 App 및 웹사이트)에 표시되는 비디오 조회수 지표와 다양한 Engagement API 엔드포인트를 통해 수신하는 수치 사이에 차이가 발생할 수 있다는 점을 유의해 주세요.

• /totals 엔드포인트와 X 사용자 인터페이스에서 제공되는 비디오 조회수는 특정 비디오가 게시된 모든 포스트에 걸쳐 집계된 비디오 조회수를 표시합니다. 즉, /totals를 통해 전달되고 X UI에 표시되는 지표에는 해당 비디오가 리트윗되었거나 별도의 포스트로 다시 게시된 모든 경우의 조회수가 합산되어 포함됩니다.
• /28hour 및 /historical Engagement API 엔드포인트에서 제공되는 비디오 조회수는 사용자가 지표를 조회하는 특정 포스트에서 발생한 조회수만 포함합니다.   

또한, 1,800일이 지난 포스트에 대해서는 비디오 조회수를 제공하지 않는다는 점에 유의해 주세요. 대신, 1,800일이 지난 포스트 목록을 담은 객체를 제공합니다. 요청한 포스트에 대한 다른 모든 지표는 별도의 객체로 계속 수신하게 됩니다. 아래는 예시 응답입니다:

{
  "unsupported_for_video_views_tweet_ids": [
    "479311209565413376",
    "477139122520219648"
  ],
  "grouping name": {
    "479311209565413376": {
      "favorites": "69",
      "impressions": "1692",
      "retweets": "142",
      "video_views": "0"
    },
    "477139122520219648": {
      "favorites": "10",
      "impressions": "1023",
      "retweets": "6",
      "video_views": "0"
    },
    "1397568983931392004": {
      "favorites": "268",
      "impressions": "26803",
      "retweets": "56",
      "video_views": "17902"
    }
  }
}

Media Views 지표는 /28hour 및 /historical 엔드포인트에서 소유한 포스트에 대해서만 제공됩니다.

​

Engagement API 그룹화

그룹화를 사용하면 반환된 참여(engagement) 지표를 원하는 방식으로 구성할 수 있습니다. 요청당 최대 3개의 그룹화를 포함할 수 있습니다. 아래 값들 중 하나 이상으로 지표를 그룹화할 수 있습니다:

세 개의 엔드포인트 모두에서 지원하는 항목:

• tweet.id
• engagement.type  

/28hr 및 /historical 엔드포인트는 시계열(time-series) 지표를 제공할 수 있으므로, 다음도 지원합니다:

• engagement.day
• engagement.hour

그룹화는 순차적으로 적용되므로, group_by 값들의 순서를 변경하여 원하는 결과 형식을 바꿀 수 있습니다. 네 개의 group_by 값을 사용하는 그룹화는 다음 두 가지 형식 중 하나에서만 지원됩니다:

"group_by": [
    "tweet.id",
    "engagement.type",
    "engagement.day",
    "engagement.hour"
  ]

또는

"group_by": [
    "engagement.type",
    "tweet.id",
    "engagement.day",
    "engagement.hour"
]

예를 들어, metric type별 총합계를 생성하려면 요청에 다음과 같은 “groupings” 명세를 포함하세요(요청 구성 방법에 대한 자세한 내용은 API 참조 문서 페이지를 참조하세요).

{
  "engagement_types": [
    "favorites",
    "replies",
    "retweets"
  ],
  "groupings": {
    "Grand Totals": {
      "group_by": [
        "engagement.type"
      ]
    }
  }
}

이 그룹화를 사용하면 Engagement API의 JSON 응답에 루트 수준 "Grand Totals" 속성이 포함되며, 여기에는 지표 type별 전체 합계가 담깁니다.

{
  "Grand Totals": {
    "favorites": "12",
    "replies": "2",
    "retweets": "2"
  }
}

단일 게시물에 대해 게시물 id별로 그룹화된 4시간 분량의 시계열 메트릭을 생성하려면, 요청에 다음과 같은 Grouping 사양을 포함해야 합니다:

{
  "start": "2016-02-10T17:00:00Z",
  "end": "2016-02-10T21:00:00Z",
  "tweet_ids": [
    "697506383516729344"
  ],
  "engagement_types": [
    "impressions",
    "engagements"
  ],
  "groupings": {
    "Tweets_MetricType_TimeSeries": {
      "group_by": [
        "tweet.id",
        "engagement.type",
        "engagement.hour"
      ]
    }
  }
}

이 그룹화를 사용하면 Engagement API의 JSON 응답에 루트 수준의 "Tweets_MetricType_TimeSeries" 속성이 포함되며, 여기에는 먼저 게시물 ID별로, 그다음 메트릭 type별로 구분된 메트릭과 해당 시간 단위 시계열이 담깁니다.

{
  "Tweets_MetricType_TimeSeries": {
    "697506383516729344": {
      "impressions": {
        "2016-02-10": {
          "17": "551",
          "18": "412",
          "19": "371",
          "20": "280"
        }
      },
      "engagements": {
        "2016-02-10": {
          "17": "8",
          "18": "6",
          "19": "3",
          "20": "0"
        }
      }
    }
  }
}

​

자주 묻는 질문

Enterprise

​

Engagement API

Engagement API에는 어떻게 액세스할 수 있나요?

Engagement API 액세스는 엔터프라이즈 구독을 통해 제공됩니다. 영업 팀과 연락하기 위해 이 양식을 작성해 주세요.

내 사용량은 '@handle' 기준으로 어떻게 추적되나요?

계약에 Engagement API와 함께 사용할 수 있는 고유 handle 개수에 대한 한도가 포함되어 있는 경우, 내부 X 시스템은 Engagement API로 조회된 게시물을 소유한 인증된 사용자 수를 추적합니다. 고객도 클라이언트 측에서 이 고유한 수치를 직접 추적해야 합니다. 현재 Engagement API의 @handle 사용량을 확인할 수 있는 사용량 API 또는 UI는 없습니다. 계약된 양보다 더 많은 @handle이 요청되더라도 시스템이 이를 차단하지는 않습니다. 청구 월이 끝나면 조회된 고유 @handle 수가 계약된 수량과 비교되며, 계약 조건에 따라 초과 사용량이 청구됩니다.

Engagement API에 대한 @handle 사용량을 확인할 수 있나요?

현재 Engagement API의 @handle 사용량을 확인할 수 있는 사용량 API 또는 UI는 없습니다. 계약된 양보다 더 많은 @handle이 요청되더라도 시스템이 이를 차단하지는 않습니다. 청구 월이 끝나면 조회된 고유 @handle 수가 계약된 수량과 비교되며, 계약 조건에 따라 초과 사용량이 청구됩니다.

페이로드에 반환된 engagements 메타데이터 필드가 다양한 참여(engagement) 지표 합계의 총합과 같지 않습니다. 왜 그런가요?

이는 정상적인 동작입니다. engagements 메타데이터 필드는 API가 반환하는 개별 참여 지표 합계와 항상 일치하지 않을 수 있습니다. 이는 engagements 메타데이터 필드에 페이로드에서 별도 지표로 분리되어 있지 않은 추가 참여가 포함될 수 있기 때문입니다. 다시 말해, 다양한 참여 지표의 총합을 모두 더하더라도 페이로드의 engagements 메트릭 필드에 반환되는 값과 일치하지 않을 수 있습니다.

engagements 메타데이터 필드는 게시물에 대해 발생한 모든 클릭 또는 상호작용으로 이해하시면 됩니다.  

페이로드 응답의 url_clicks 필드가 숫자를 반환하지만, 실제로 해당 게시물에는 URL이 없습니다. 어떻게 이런 일이 가능한가요?

이는 해시태그처럼 다른 페이지로 연결되는 링크를 생성하는 요소를 포함한 게시물에서, 사용자가 이 요소를 클릭한 경우 URL 클릭으로 집계되기 때문일 수 있습니다.  

특정 게시물에 대한 참여 데이터를 받을 수 없는 이유는 무엇인가요?

특정 게시물에 대한 참여 데이터를 검색할 수 없는 이유는 여러 가지가 있으며, 다음을 포함합니다:

• 타사 대신 데이터를 조회하기 위해 사용 중인 인증 토큰 기준으로, 요청한 게시물 ID가 사용 가능하지 않은 경우
• /totals 엔드포인트에 대해 요청한 게시물 ID가 90일 이내의 게시물이 아니어서 노출수(impressions) 또는 참여 지표를 반환할 수 없는 경우
• 요청한 게시물 ID가 더 이상 사용 가능하지 않은 경우로, 일반적으로 삭제되었거나 다른 이유로 더 이상 공개적으로 제공되지 않음을 의미합니다.

위 상황 중 하나에 해당하는 경우 받게 될 수 있는 다양한 에러 메시지를 확인해 주세요.

Engagement API에서 레이트 리밋(rate limiting)은 어떻게 처리할 수 있나요?

Engagement API에 요청을 보낼 때 응답 헤더에 반환되는 x-per-minute-limit 및 x-per-minute-remaining 정보를 사용하여 사용량을 모니터링할 수 있습니다.

x-per-minute-limit는 허용량을, x-per-minute-remaining은 남은 호출 횟수를 알려줍니다.

​

오류 해결 가이드

인증에 문제가 있습니다

Engagement API에 대한 인증 가이드라인을 반드시 검토해 주세요.

올바른 consumer key와 secret, 그리고 access token과 access token secret을 전달했는데도 다음 오류가 반환됩니다. 어떻게 해야 하나요?

[
    Your account could not be authenticated. Reason: Unknown Authorization Type;
]

/totals 엔드포인트로 인증을 시도할 때는 어떤 access token이나 secret도 사용하지 마세요. 이러한 토큰을 포함한 상태에서 해당 토큰과 연결되지 않은 게시물의 콘텐츠를 가져오려고 하면 다음과 같은 오류를 받게 될 가능성이 높습니다:

[
    Forbidden to access tweets: 1054424731825229824;
]

​

원하시는 정보를 아직 찾지 못하셨나요?

아직 답을 찾지 못한 질문이 있습니다

기술 지원 팀으로 문의해 주시면 신속하게 답변드리겠습니다.

​

API 참조 문서

​

POST insights/engagement

​

메서드

Method	Description
POST /insights/engagement/totals	Tweet 모음에 대한 총 노출 수와 참여 수를 조회합니다.
POST /insights/engagement/historical	최대 4주 기간에 대해, 2014년 9월 1일까지 소급하여 Tweet 모음의 노출 수와 참여 수를 조회합니다.
POST /insights/engagement/28hr	지난 28시간 동안의 Tweet 모음에 대한 노출 수와 참여 수를 조회합니다.

​

Authentication

Engagement API는 HTTPS 사용을 요구하며, User Context와 Application-Only OAuth 두 방식을 모두 지원합니다. Engagement API에 대한 대부분의 요청에는 3-Legged OAuth(특정 버전의 User Context) 사용이 필요합니다. 이는 Twitter 계정 매니저로부터 Engagement API 접근 권한을 부여받은 App의 consumer key 및 secret과 함께, Tweet 소유자의 access token 및 access token secret을 사용하여 엔드포인트를 호출해야 한다는 의미입니다. 다음 요청에는 이 유형의 OAuth가 필요합니다:

• 소유한 Tweet에 한정되는 Impressions 및 Engagements 지표 type을 얻기 위한 /totals에 대한 모든 요청
• /28hr에 대한 모든 요청
• /historical에 대한 모든 요청

일부 Engagement API 요청은 Application-Only OAuth를 사용하여 수행할 수 있습니다. 이 경우 consumer key와 secret 또는 Bearer 토큰만 제공하면 됩니다. 다음 요청은 이 유형의 OAuth로 수행할 수 있습니다:

• 모든 Tweet에 대해 조회할 수 있는 Favorites, Replies, Retweets 또는 Video Views 지표 type을 얻기 위한 /totals에 대한 모든 요청

어떤 요청이든, developer.x.com에 있는 App 관리 콘솔을 사용해 Twitter App과 해당 API 키를 설정해야 합니다.

참고: developer.x.com에 로그인한 Twitter 계정이 있다면, Twitter apps를 Twitter app 대시보드를 통해 조회 및 편집할 수 있습니다.

App을 설정한 후에는, App이 Engagement API에 대한 요청을 보낼 수 있도록 App ID가 계정 담당자의 승인을 받아야 합니다. Access token은 “현재 사용자”를 나타내는 데 사용되어야 하며, 다른 사용자를 대신해 요청을 수행하는 경우 유효한 토큰으로 서명해야 합니다. OAuth signature base string을 준비하기 전에 URL 및 POST body 내에서 예약 문자 인코딩이 적절히 이루어지고 있는지 확인하십시오.

OAuth를 시작하는 방법에 대한 자세한 내용은 다음 링크를 참고하십시오:

• OAuth 개요
• User Context라고도 불리는 3-Legged OAuth 사용하기
• Application-Only OAuth 사용하기

​

POST /insights/engagement/totals

totals 엔드포인트를 사용하면 한 번의 요청으로 최대 250개의 Tweet에 대한 현재 총 노출 수와 참여 수를 조회할 수 있습니다.

요청 메서드	HTTP POST
URL	https://data-api.x.com/insights/engagement/totals
콘텐츠 유형	application/json
압축	Gzip. Gzip 압축을 사용하여 요청하려면 연결 요청에 Accept-Encoding 헤더를 포함하세요. 헤더는 다음과 같이 설정합니다: Accept-Encoding: gzip
POST 요청 형식	요청은 본문에 여러 Tweet ID와 원하는 그룹핑이 포함된 JSON 객체를 담은 POST 요청으로 전송할 수 있습니다. POST 본문은 tweets, engagements, groupings 객체를 요소로 하는 배열 형식입니다. 각 요청에는 최대 250개의 Tweet ID를 포함할 수 있습니다. 예시 POST body는 다음과 같습니다. { “tweet_ids”: [ “Tweet ID 1”, “Tweet ID 2”, “Tweet ID 3” ], “engagement_types”: [ “impressions”, “engagements”, “favorites”, “quote_tweets” ], “groupings”: { “grouping name”: { “group_by”: [ “tweet.id”, “engagement.type” ] } } }
Tweet ID 목록	조회할 참여(engagement) 데이터에 대한 Tweet ID의 배열입니다. 인증에 사용된 @handle 계정이 작성한 Tweet에 대해서만 데이터를 요청할 수 있습니다. 요청당 최대 250개의 Tweet을 포함할 수 있으며, Tweet ID는 문자열로 전달해야 합니다.
참여 유형	질의할 참여 지표 유형을 포함하는 배열입니다. Totals 엔드포인트는 다음과 같은 참여 지표 유형만 지원합니다: impressions, engagements, favorites, retweets, quote_tweets, replies, video_views. /totals 엔드포인트를 사용하면 지난 90일 이내에 생성된 Tweet에 대해서는 impressions 및 engagements를, 그리고 어떤 Tweet이든 favorites, retweets, quote_tweets, replies, video_views를 조회할 수 있습니다.
그룹화	Engagement API의 결과는 다양한 방식으로 그룹화하여 반환할 수 있으므로, 요구 사항에 가장 잘 맞게 설정할 수 있습니다. 요청당 최대 3개의 grouping을 포함할 수 있습니다. 각 grouping에 대해, 애플리케이션에서 이 그룹 유형을 더 쉽게 참조할 수 있도록 사용자 지정 그룹 이름을 정의할 수 있습니다. 그룹 이름을 정의한 후에는 tweet.id 및/또는 engagement.type을 기준으로 그룹화하도록 선택할 수 있습니다. Groupings는 순차적으로 적용되므로, group_by 값의 순서를 변경하여 원하는 결과 형식을 변경할 수 있습니다. Tweet ID 및 지표 유형별로 구분된 지표를 보여 주는 grouping 예시는 다음과 같습니다. “groupings”: { “my grouping name”: { “group_by”: [ “tweet.id”, “engagement.type” ] } }
POST 요청 크기 제한	요청은 한 번에 최대 250개의 Tweet ID에 대해서만 보낼 수 있습니다.
응답 형식	JSON. 응답을 JSON 형식으로 받으려면 요청 헤더에 JSON 형식을 명시해야 합니다.
요청 제한	액세스 수준과 계약 조건에 따라, 분 단위로 레이트 리밋이 적용됩니다.
예시 요청 (공개 메트릭)	curl —request POST —url https://data-api.x.com/insights/engagement/totals —header ‘accept-encoding: gzip’ —header ‘authorization: Bearer ’ —header ‘content-type: application/json’ —data ’{ “tweet_ids”: [ “1070059276213702656”,“1021817816134156288”,“1067094924124872705” ], “engagement_types”: [ “favorites”,“retweets”,“replies”,“quote_tweets”,“video_views” ], “groupings”: { “perTweetMetricsUnowned”: { “group_by”: [ “tweet.id”, “engagement.type” ] } } } —verbose —compressed
요청 예시	curl —request POST —url https://data-api.x.com/insights/engagement/totals —header ‘accept-encoding: gzip’ —header ‘authorization: OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’ —header ‘content-type: application/json’ —data ’{ “tweet_ids”: [ “1060976163948904448”,“1045709644067471360” ], “engagement_types”: [ “favorites”,“replies”,“retweets”,“video_views”,“impressions”,“engagements” ], “groupings”: { “perTweetMetricsOwned”: { “group_by”: [ “tweet.id”, “engagement.type” ] } } }’ —verbose —compressed
예시 응답 (공개 지표)	{ “perTweetMetricsUnowned”: { “1021817816134156288”: { “favorites”: “530”, “quote_tweets”: “79”, “replies”: “147”, “retweets”: “323”, “video_views”: “0” }, “1067094924124872705”: { “favorites”: “1360”, “quote_tweets”: “29”, “replies”: “56”, “retweets”: “178”, “video_views”: “5754512” }, “1070059276213702656”: { “favorites”: “69”, “quote_tweets”: “5”, “replies”: “7”, “retweets”: “26”, “video_views”: “0” } } }
응답 예시	{ “perTweetMetricsOwned”: { “1045709644067471360”: { “engagements”: “2”, “favorites”: “0”, “impressions”: “47”, “replies”: “0”, “retweets”: “8”, “quote_tweets”: “5”, “video_views”: “0” }, “1060976163948904448”: { “engagements”: “4”, “favorites”: “0”, “impressions”: “148”, “replies”: “1”, “retweets”: “9”, “quote_tweets”: “2”, “video_views”: “0” } } }
이용할 수 없는 Tweet ID	더 이상 제공되지 않는 Tweet ID(예: 삭제된 경우)를 포함하는 쿼리의 경우, 사용 가능한 모든 Tweet ID에 대해서는 해당 데이터가 반환되며, 사용 불가능한 Tweet ID는 unavailable_tweet_ids라는 배열에 포함됩니다. 예시: { “start”: “2015-11-17T22:00:00Z”, “end”: “2015-11-19T02:00:00Z”, “unavailable_tweet_ids”: [ “323456789” ], “group1”: { “423456789”: { “favorites”: “67”, “replies”: “8”, “retweets”: “26”, “quote_tweets”: “2” } } }

​

POST /insights/engagement/28hr

28시간 엔드포인트는 지난 28시간 동안 최대 25개의 Tweet 컬렉션에 대한 노출 수(impressions)와 참여 수(engagements)를 조회할 수 있는 기능을 제공합니다. 또한 지원되는 모든 개별 지표(metrics)에 대해 값을 요청할 수 있습니다. 지원되는 지표의 전체 목록은 Metric Availability를 참고하세요.

요청 메서드	HTTP POST
URL	https://data-api.x.com/insights/engagement/28hr
콘텐츠 유형	application/json
압축	Gzip. Gzip 압축을 사용해 요청하려면 연결 요청에 Accept-Encoding 헤더를 포함해 전송하십시오. 헤더 형식은 다음과 같습니다. Accept-Encoding: gzip
POST 형식	요청은 본문에 Tweet ID 모음과 원하는 그룹화를 포함하는 JSON 객체를 담은 POST 요청으로 전송할 수 있습니다. POST 본문은 tweets, engagements, groupings 객체로 이루어진 배열 형태입니다. 각 요청에는 최대 25개의 Tweet ID를 포함할 수 있습니다. 예시 POST 본문은 다음과 같습니다. { “tweet_ids”: [ “Tweet ID 1”, “Tweet ID 2”, “Tweet ID 3” ], “engagement_types”: [ “impressions”, “engagements”, “url_clicks”, “detail_expands” ], “groupings”: { “grouping name”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.hour” ] } } }
Tweet ID 목록	조회하려는 Tweet의 참여(engagement) 데이터에 대한 Tweet ID 배열입니다. 인증에 사용한 @handle 계정이 작성한 Tweet에 대해서만 데이터를 요청할 수 있습니다. 28시간 엔드포인트는 요청 한 번당 최대 25개의 Tweet까지 지원하며, Tweet ID는 문자열로 표현해야 합니다.
참여 지표 유형	조회할 참여 지표 유형을 담은 배열입니다. 28시간 엔드포인트의 경우 impressions, engagements 및 모든 개별 참여 유형이 지원되는 지표입니다. 지원되는 참여 지표의 전체 목록은 Engagement Data를 참고하세요.
그룹화	Engagement API의 결과는 요구 사항에 가장 잘 맞도록 서로 다른 그룹으로 반환될 수 있습니다. 하나의 요청당 최대 3개의 그룹을 포함할 수 있습니다. 각 그룹에 대해, 애플리케이션에서 이 그룹 유형을 더 쉽게 참조할 수 있도록 사용자 지정 그룹 이름을 정의할 수 있습니다. 그룹 이름을 정의한 후에는 다음 값들 중 하나 이상을 기준으로 그룹화하도록 선택할 수 있습니다: tweet.id engagement.type engagement.day engagement.hour 그룹은 순차적으로 처리되므로, group_by 값의 순서를 변경하여 원하는 결과 형식을 조정할 수 있습니다. 다음은 Tweet ID, 지표 유형, 날짜별로 분리된 지표를 보여주는 그룹화 예시이며, 형식은 다음과 같습니다: “groupings”: { “my grouping name”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day” ] } } 4개의 group_by 항목을 가진 그룹은 아래 두 가지 순서 중 하나를 사용할 때만 유효합니다. 단일 그룹 내에 4개의 group_by 항목이 있으면서 아래에 해당하지 않는 요청은 오류를 반환합니다. 또한, 요청당 4개의 group_by 항목을 가진 그룹은 하나만 허용됩니다. “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day”, “engagement.hour” ] “group_by”: [ “engagement.type”, “tweet.id”, “engagement.day”, “engagement.hour” ]
POST 요청 크기 제한	한 번에 최대 25개의 Tweet ID에 대해 요청할 수 있습니다.
응답 형식	JSON. 요청 헤더에서 응답 형식을 JSON으로 지정해야 합니다.
요청 제한	계약서에 명시된 액세스 수준에 따라 분 단위 레이트 리밋이 적용됩니다.
요청 예제	curl -X POST “https://data-api.x.com/insights/engagement/28hr” -H ‘Accept-Encoding: gzip’ -H ‘Authorization OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’ -d ’{ “tweet_ids”: [ “123456789” ], “engagement_types”: [ “impressions”, “engagements” ], “groupings”: { “hourly-time-series”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day”, “engagement.hour” ] } } }‘
응답 예시	{ “시작”:“2015-09-14T17:00:00Z”, “end”:“2015-09-15T22:00:00Z”, “hourly-time-series”:{ “123456789”:{ “impressions”:{ “2015-09-14”:{ “17”:“551”, “18”:“412”, “19”:“371”, “20”:“280”, “21”:“100”, “22”:“19”, “23”:“6” }, “2015-09-15”:{ “00”:“5”, “01”:“2”, “02”:“7”, “03”:“3”, “04”:“1”, “05”:“0”, “06”:“0”, “07”:“0”, “08”:“0”, “09”:“0”, “10”:“0”, “11”:“0”, “12”:“0”, “13”:“0”, “14”:“0”, “15”:“0”, “16”:“0”, “17”:“0”, “18”:“0”, “19”:“0”, “20”:“0”, “21”:“0” } }, “engagements”:{ “2015-09-14”:{ “17”:“0”, “18”:“0”, “19”:“0”, “20”:“0”, “21”:“0”, “22”:“0”, “23”:“0” }, “2015-09-15”:{ “00”:“0”, “01”:“0”, “02”:“0”, “03”:“0”, “04”:“0”, “05”:“0”, “06”:“0”, “07”:“0”, “08”:“0”, “09”:“0”, “10”:“0”, “11”:“0”, “12”:“0”, “13”:“0”, “14”:“0”, “15”:“0”, “16”:“0”, “17”:“0”, “18”:“0”, “19”:“0”, “20”:“0”, “21”:“0” } } } } }
사용 불가능한 Tweet ID	사용할 수 없게 된 Tweet ID(예: 삭제된 경우)를 포함하는 쿼리를 실행하면, 사용 가능한 모든 Tweet ID에 대해서는 적절한 데이터가 반환되고, 사용할 수 없는 Tweet ID는 unavailable_tweet_ids라는 배열에 나열됩니다. 예를 들어: { “start”: “2015-11-17T22:00:00Z”, “end”: “2015-11-19T02:00:00Z”, “unavailable_tweet_ids”: [ “323456789” ], “group1”: { “423456789”: { “favorites”: “67”, “replies”: “8”, “retweets”: 26 } } }

​

POST /insights/engagement/historical

이 historical 엔드포인트는 최대 25개의 Tweet으로 구성된 컬렉션에 대해 최대 4주 기간 동안의 노출수(impressions)와 참여수(engagement)를 조회할 수 있는 기능을 제공합니다. 현재 2014년 9월 1일 이전의 데이터는 API를 통해 요청할 수 없습니다. historical 엔드포인트는 또한 지원되는 모든 개별 지표에 대한 metric을 요청할 수 있는 기능도 제공합니다. 지원되는 metric의 전체 목록은 Metric Availability를 참고하세요.

요청 메서드	HTTP POST
URL	https://data-api.x.com/insights/engagement/historical
콘텐츠 유형	application/json
압축 방식	Gzip. Gzip 압축을 사용하여 요청을 보내려면 연결 요청에 Accept-Encoding 헤더를 포함하세요. 헤더는 다음과 같이 지정합니다. Accept-Encoding: gzip
POST 요청 형식	요청은 POST 요청으로 전송할 수 있으며, 이때 body는 Tweet ID 컬렉션과 원하는 그룹화를 포함하는 JSON 객체입니다. POST body는 tweets, engagements, groupings 객체를 포함한 배열 형식으로 구성됩니다. 각 요청에는 최대 25개의 Tweet ID를 포함할 수 있습니다. 각 요청에는 최대 4주까지의 기간에 대해 사용자 지정 Start와 End 날짜를 지정할 수 있습니다. { “tweet_ids”: [ “Tweet ID 1”, “Tweet ID 2”, “Tweet ID 3” ], “engagement_types”: [ “impressions”, “engagements”, “url_clicks”, “detail_expands” ], “groupings”: { “grouping name”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.hour” ] } } }
시작 및 종료일	요청의 일부로 start 및 end 값을 사용하여 사용자 지정 시작일과 종료일을 지정할 수 있습니다. 시작일과 종료일은 기간이 4주를 초과하지 않도록 지정해야 합니다. 현재 설정할 수 있는 가장 이른 시작일은 2014년 9월 1일입니다. 미래 시점의 종료일은 지원되지 않습니다. 시작일과 종료일을 제공하지 않으면 API는 직전 4주간을 기본값으로 사용합니다. Engagement API에서 데이터를 반환할 수 있는 가장 낮은 세분화 단위는 시간(hour)입니다. Start 또는 End 값이 정확히 정각 경계에 맞지 않는 요청의 경우, 요청은 가장 가까운 포함 정각으로 기본 설정됩니다. 예를 들어, “start”:“2015-07-01T12:24:00Z” 및 “end”:“2015-07-10T08:37:00Z” 값을 사용한 요청은 “start”:“2015-07-01T12:00:00Z”,“end”:“2015-07-10T09:00:00Z”으로 기본 설정됩니다.
Tweet ID	조회할 참여(engagement) 데이터를 대상으로 하는 Tweet ID의 배열입니다. 인증을 수행한 @handle 계정이 작성한 Tweet에 대해서만 데이터를 요청할 수 있습니다. 최근 4주 조회 엔드포인트는 요청당 최대 25개의 Tweet만 지원하며, Tweet ID는 문자열로 전달해야 합니다.
참여 유형	조회할 참여 지표 유형을 나열한 배열입니다. 4주 히스토리컬 엔드포인트에서는 impressions, engagements 및 모든 개별 참여 유형 지표가 지원됩니다. 지원되는 참여 지표의 전체 목록은 Engagement Data를 참조하세요. Note: 현재 2015년 9월 15일 이전 시점을 대상으로 쿼리하는 경우 favorites, replies, retweets 세 가지 지표는 0으로 표시됩니다.
그룹화	Engagement API의 결과는 요구 사항에 가장 잘 맞도록 여러 그룹으로 나누어 반환할 수 있습니다. 하나의 요청에는 최대 3개의 grouping을 포함할 수 있습니다. 각 grouping마다, 애플리케이션에서 이 grouping type을 더 쉽게 참조할 수 있도록 사용자 지정 grouping 이름을 정의할 수 있습니다. grouping 이름을 정의한 후에는 다음 값들 중 하나 이상을 기준으로 그룹화하도록 선택할 수 있습니다: tweet.id engagement.type engagement.day engagement.hour Groupings는 순차적으로 적용되므로, group_by 값의 순서를 변경하여 원하는 결과 형식을 바꿀 수 있습니다. 다음은 Tweet ID, 지표 type, 일(day)별로 구분된 metric을 보여주는 grouping 예시입니다: “groupings”: { “my grouping name”: { “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day” ] } } 4개의 group_by 항목을 가진 grouping은 아래 두 가지 순서 중 하나를 사용할 때만 유효합니다. 하나의 grouping에서 4개의 group_by 항목을 사용하면서 아래 두 가지 순서 중 어느 것도 사용하지 않은 요청은 오류를 반환합니다. 추가로, 요청당 4개의 group_by 항목을 가진 grouping은 하나만 허용됩니다. “group_by”: [ “tweet.id”, “engagement.type”, “engagement.day”, “engagement.hour” ] “group_by”: [ “engagement.type”, “tweet.id”, “engagement.day”, “engagement.hour” ]
POST 요청 한도	요청당 최대 25개의 Tweet ID까지 지정할 수 있습니다.
응답 형식	JSON. 요청 헤더에서 응답 형식으로 JSON을 지정해야 합니다.
요청 제한	접근 수준과 계약 조건에 따라, 분(minute) 단위 Rate Limit(요청 한도)이 적용됩니다.
요청 예시	curl -XPOST “https://data-api.x.com/insights/engagement/historical” -H ‘Accept-Encoding: gzip’ -H ‘Authorization OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’ -d ’{ “start”: “2015-08-01”, “end”: “2015-08-15”, “tweet_ids”: [ “123456789”, “223456789”, “323456789” ], “engagement_types”: [ “impressions”, “engagements”, “url_clicks”, “detail_expands” ], “groupings”: { “types-by-tweet-id”: { “group_by”: [ “tweet.id”, “engagement.type” ] } } }‘
응답 예시	{ “start”: “2015-08-01T00:00:00Z”, “end”: “2015-08-15T00:00:00Z”, “types-by-tweet-id”: { “123456789”: { “impressions”: “0”, “engagements”: “0”, “url_clicks”: “0”, “detail_expands”: “0” }, “223456789”: { “impressions”: “788”, “engagements”: “134”, “url_clicks”: “30”, “detail_expands”: “1323” }, “323456789”: { “impressions”: “4”, “engagements”: “0”, “url_clicks”: “2”, “detail_expands”: “0” } } }
사용할 수 없는 Tweet ID	사용할 수 없게 된 Tweet ID(예: 삭제된 경우)가 포함된 쿼리의 경우, 사용 가능한 모든 Tweet ID에 대해서는 적절한 데이터가 반환되며, 사용할 수 없는 Tweet ID는 unavailable_tweet_ids라는 배열에 나열됩니다. 예를 들어: { “start”: “2015-11-17T22:00:00Z”, “end”: “2015-11-19T02:27:50Z”, “unavailable_tweet_ids”: [ “323456789” ], “group1”: { “423456789”: { “favorites”: “67”, “replies”: “8”, “retweets”: 26 } } }

​

응답 코드

Status	Text	Description
200	OK	요청이 성공적으로 처리되었습니다.
400	Bad Request	일반적으로 이 응답은 요청에 유효하지 않은 JSON이 포함되어 있거나, 요청에서 JSON 페이로드를 전혀 보내지 않은 경우 발생합니다.
401	Unauthorized	잘못된 자격 증명으로 인해 HTTP 인증에 실패했습니다. OAuth 키와 토큰을 확인하세요.
404	Not Found	요청이 전송된 URL에서 리소스를 찾을 수 없습니다. 잘못된 URL을 사용했을 가능성이 큽니다.
429	Too Many Requests	앱이 API 요청 한도를 초과했습니다.
500	Internal Server Error	Gnip 측에서 오류가 발생했습니다. 지수적 백오프 패턴을 사용하여 요청을 재시도하세요.
502	Proxy Error	Gnip 측에서 오류가 발생했습니다. 지수적 백오프 패턴을 사용하여 요청을 재시도하세요.
503	Service Unavailable	Gnip 측에서 오류가 발생했습니다. 지수적 백오프 패턴을 사용하여 요청을 재시도하세요.

​

오류 메시지

여러 상황에서 Engagement API는 상황별 오류 메시지를 반환하며, 애플리케이션은 이에 적절히 대응할 수 있어야 합니다. 아래 표에는 이러한 오류 메시지의 일반적인 예와, 이를 어떻게 해석해야 하는지가 나와 있습니다. 많은 경우 Engagement API는 추가 정보를 담은 200 OK 응답의 일부로, 사용 가능한 데이터에 대한 부분 결과와 함께 특정 오류 메시지를 반환한다는 점에 유의하세요.

Error Message	Description
"errors":["Your account could not be authenticated. Reason: Access token not found"]	요청의 인증 구성 요소에서 발생한 오류입니다. “Reason” 항목에는 오류를 해결하는 데 도움이 되는 정보가 제공됩니다. 문제를 해결할 수 없는 경우, “Reason”을 포함한 전체 오류 메시지를 지원 팀에 보내 주세요.
"errors":["1 Tweet ID(s) are unavailable"],"unavailable_tweet_ids": ["TWEET_IDS"]	요청한 Tweet ID(들)를 더 이상 사용할 수 없습니다. 일반적으로 삭제되었거나, 다른 이유로 더 이상 공개적으로 제공되지 않음을 의미합니다.
"errors":["Impressions & engagements for tweets older than 90 days (*TIME_PERIOD*) are not supported"],"unsupported_for_impressions_engagements_tweet_ids":[*TWEET_IDS*]	/totals 엔드포인트에 대해 요청한 Tweet ID(들)가 90일 이내에 생성된 Tweet이 아니므로, impressions 또는 engagements 지표를 반환할 수 없습니다.
"errors":["Forbidden to access tweets: *TWEET_IDS*"]	제3자를 대신해 데이터를 조회하기 위해 사용 중인 인증 토큰으로는, 요청한 Tweet ID(들)에 접근할 수 없습니다.