메인 콘텐츠로 건너뛰기

​
개요

Enterprise 이는 관리형 액세스 레벨에서만 제공되는 엔터프라이즈 API입니다. 이 API를 사용하려면 먼저 엔터프라이즈 영업팀과 계정을 개설해야 합니다. 자세히 알아보기 Engagement API는 게시물 노출 수와 참여 지표에 대한 액세스를 제공합니다. 대부분의 지표와 엔드포인트는 OAuth 1.0a 사용자 컨텍스트로 인증해야 하지만, OAuth 2.0 베어러 토큰과 /totals 엔드포인트를 사용하면 공개 Favorite, Retweet, Reply, Video Views 지표에 액세스할 수 있습니다.   참고: 일부 X 웹 대시보드에 보고된 데이터와 Engagement API에 보고된 데이터 간에는 차이가 있을 수 있습니다. 이는 웹 대시보드가 일반적으로 선택한 기간 내에 발생한 참여 및/또는 노출만 표시하기 때문입니다. 예를 들어, 웹 대시보드는 달력상 한 달 동안의 게시물 참여만 표시할 수 있지만, Engagement API는 요청한 시간 범위 내라면 그 달을 넘어 발생한 참여도 표시할 수 있습니다. 이러한 경우에는 Engagement API를 신뢰할 수 있는 기준으로 간주해야 합니다.  

​
요청 엔드포인트

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

​
현재 합계: [/totals]

  • 요청은 원하는 게시물에 대해 노출수 합계 지표와 참여수 합계 지표를 반환합니다
  • 다음 지표로 제한됩니다: Impressions, Engagements, Favorites, Replies, Retweets, Quote Tweets, Video Views
  • OAuth 1.0a 사용자 컨텍스트를 사용하여 최근 90일 이내 생성된 게시물의 Impressions 및 Engagements 지표 조회를 지원합니다
  • OAuth 2.0 베어러 토큰을 사용하여 모든 게시물에 대한 Favorites, Retweets, Quote Tweets, Replies, 및 Video Views 지표 조회를 지원합니다
  • 결과는 요청 시점의 현재 노출수와 참여수 합계를 기준으로 합니다
  • 다양한 @handle 전반에서 대시보드 보고를 구동하고 참여율을 계산하는 데 이상적입니다
  • 요청당 최대 250개의 게시물에 대한 지표 요청을 지원합니다  

​
지난 28시간: [/28hr]

  • 요청은 노출수 총합 지표, 참여수 총합 지표, 그리고 지난 28시간 동안 발생한 개별 참여 지표의 세부 내역을 반환할 수 있습니다
  • 데이터는 게시물 id별로, 그리고 집계된 시계열에서 일 단위 또는 시간 단위로 그룹화할 수 있습니다
  • 최근 생성된 콘텐츠의 성과를 추적하는 데 이상적입니다
  • 사용 가능한 모든 지표를 지원합니다
  • 요청당 게시물 최대 25개의 지표 조회를 지원합니다  

​
기록: [/historical]

  • 요청은 최근 1년 동안의 노출 수, 참여 수, 그리고 개별 참여 지표의 세부 항목을 반환할 수 있으며, 기준은 게시물 생성 시간이 아니라 참여 시간입니다.
  • 요청은 시작 날짜와 종료 날짜 매개변수를 지원하여 최대 4주 기간 내에서 특정 기간으로 범위를 좁힐 수 있는 유연성을 제공합니다.
  • 게시물 참여 데이터는 과거 365일까지만 제공합니다.
  • 데이터는 게시물 ID별로, 그리고 시계열 집계로서 일 단위 또는 시간 단위로 그룹화할 수 있습니다.
  • 최근 성과를 과거 기준과 비교 평가하거나 @handle의 성과에 대한 역사적 관점을 구축하는 데 적합합니다.
  • 사용 가능한 모든 지표를 지원합니다.
  • 요청당 최대 25개의 게시물에 대한 지표 요청을 지원합니다.

​
사용 가능한 지표

아래 표는 Engagement API에서 확인할 수 있는 지표 유형을 설명합니다. 아래 지표에 대해 더 알아보려면 지표 해석 페이지를 참조하세요.
지표엔드포인트 가용성사용자 컨텍스트 필요설명
impressionsAllYes게시물이 조회된 횟수입니다. 이 지표는 지난 90일 이내에 게시된 게시물에 대해서만 사용할 수 있습니다.
engagementsAllYes사용자가 게시물과 상호작용한 횟수입니다. 이 지표는 지난 90일 이내에 게시된 게시물에 대해서만 사용할 수 있습니다.
favoritesAllYes - /28hrs & /Historical

No - /totals		게시물이 즐겨찾기에 추가된 횟수입니다.
retweetsAllYes - /28hrs & /Historical

No - /totals		게시물이 리트윗된 횟수입니다.
quote_tweets/totalsNo - /totals게시물이 댓글과 함께 리트윗된(인용이라고도 함) 횟수입니다.
repliesAllYes - /28hrs & /Historical

No - /totals		게시물에 답글이 달린 횟수입니다.
video_viewsAllYes - /28hrs & /Historical

No - /totals		해당 게시물의 동영상이 최소 2초 동안 50% 이상 표시된 횟수입니다.

동영상 조회수는 1800일 이하의 게시물에 대해서만 사용할 수 있습니다. 1800일보다 오래된 게시물에 대해 동영상 조회수를 요청하려고 하면 요청한 다른 지표가 포함된 별도의 객체와 함께 응답 내에 다음 객체가 표시됩니다:

“unsupported_for_video_views_tweet_ids”: [“TWEET_ID”]

참고: X 소유 및 운영 플랫폼(모바일 앱 및 웹사이트)에 표시되는 동영상 조회수 지표와 /28hr 및 /historical 엔드포인트를 통해 받는 수치 사이에 차이가 있을 수 있습니다.

_ X 사용자 인터페이스 및 /totals 엔드포인트에 표시되는 동영상 조회수는 해당 동영상이 게시된 모든 게시물에서 집계된 동영상 조회수를 표시합니다. 즉, UI에 표시되는 지표에는 동영상이 리트윗되거나 별도의 게시물로 재게시된 모든 인스턴스의 조회수가 합산되어 포함됩니다. 이 지표에는 GIF의 동영상 조회수가 포함되지 않습니다.
_ /28hr 및 /historical 엔드포인트에서 제공하는 동영상 조회수에는 지표를 가져오는 특정 게시물에서 생성된 조회수만 포함됩니다. 이 지표에는 GIF의 동영상 조회수가 포함되지 않습니다.
media_views/28hr /historicalYes동영상, GIF 및 이미지에서 집계된 미디어의 모든 조회수(자동 재생 및 클릭)입니다.
media_engagements

(이전 명칭: Media Clicks)		/28hr /historicalYes게시물의 이미지 또는 동영상과 같은 미디어가 클릭된 횟수입니다.
url_clicks/28hr /historicalYes게시물의 URL이 클릭된 횟수입니다.
hashtag_clicks/28hr /historicalYes게시물의 해시태그가 클릭된 횟수입니다.
detail_expands/28hr /historicalYes게시물이 클릭되어 더 많은 세부 정보가 표시된 횟수입니다.
permalink_clicks/28hr /historicalYes게시물의 퍼머링크(이 게시물 전용 개별 웹 페이지)가 클릭된 횟수입니다.
app_install_attempts/28hr /historicalYes게시물에서 앱 설치 이벤트가 발생한 횟수입니다.
app_opens/28hr /historicalYes게시물에서 앱 열기 이벤트가 발생한 횟수입니다.
email_tweet/28hr /historicalYes게시물이 이메일을 통해 공유된 횟수입니다.
user_follows/28hr /historicalYes이 게시물에서 사용자(게시물 작성자)가 팔로우된 횟수입니다.
user_profile_clicks/28hr /historicalYes이 게시물에서 사용자(게시물 작성자)의 프로필이 클릭된 횟수입니다.

​
참여 그룹화

그룹화는 반환된 참여 지표를 원하는 방식으로 구성할 수 있게 해줍니다. 요청 한 건당 최대 3개의 그룹화를 포함할 수 있습니다. 다음 값 중 하나 이상으로 지표를 그룹화할 수 있습니다: 모든 세 엔드포인트에서 지원:
  • tweet.id
  • engagement.type  
/28hr 및 /historical은 시계열 지표를 제공할 수 있으므로 다음을 지원합니다:
  • engagement.day
  • engagement.hour
그룹화에 대해 더 알아보려면 가이드 섹션의 Engagement API Grouping 페이지를 방문하세요.

​
가이드

​
개발자 시작하기 가이드

​
소개

이 문서는 개발자에게 Engagement API 연동을 소개하기 위한 것입니다. 먼저 연동의 ‘이유’를 살펴본 뒤, 이어서 기술적인 ‘방법’의 세부 내용을 파고들겠습니다.
Engagement API는 무엇을 제공하나요?
  • Engagement API는 3-legged OAuth를 통해 해당 계정이 귀하의 앱이 자신들을 대신해 메트릭 요청을 하도록 승인했다는 전제하에, 지난 90일 동안 특정 X 계정이 소유한 게시물의 노출수 및 참여 데이터를 제공합니다. 이 강력하면서도 구현이 쉬운 솔루션은 노출수와 URL 클릭, #해시태그 클릭 등 심층 참여 지표에 즉시 접근할 수 있게 해줍니다.
  • Engagement API는 모든 게시물에 대해 즐겨찾기, 리트윗, 인용 리트윗, 답글, 동영상 조회수 등의 총합 집계 메트릭을 제공합니다. 이는 개별 게시물 또는 게시물 묶음의 기본 참여 데이터를 얻는 강력한 방법입니다.
  • Engagement API는 15개 이상의 성과 메트릭으로 콘텐츠 성과를 효과적으로 측정할 수 있게 하여, 소셜 리스닝, 마케팅, 퍼블리싱 플랫폼에 X에서의 ROI 측정이라는 새로운 가치를 제공합니다.
  • Engagement API는 요청/응답 방식의 API로, 앱 개발자가 게시물 ID, 원하는 메트릭, 기간을 포함해 요청을 보내면 API가 즉시 데이터를 반환합니다.  
왜 통합해야 할까요? 예시 사용 사례
  • 내 콘텐츠의 전체 도달 범위를 파악하여 얼마나 많은 사람이 확인했는지 알아봅니다. 동영상 조회수, 링크 클릭, 해시태그 클릭, 앱 설치 수를 확인합니다.
  • 총합 및 시계열 기반 참여 지표를 생성합니다.
  • 모든 공개 게시물에 대한 기본 참여 지표(좋아요, 리트윗, 인용 리트윗, 답글)를 파악합니다.
  • 이러한 지표를 활용해 어떤 유형의 게시물이 효과적인지 판단하여 더 자주 게시하고 노출수와 참여를 더 많이 확보합니다.
  • 내 게시물 중 하나가 좋아요 100개(또는 다른 임계값)에 도달할 때마다 마케팅 동작(예: 다른 소유 계정의 콘텐츠 리트윗)을 자동화합니다.
  • A/B 테스트를 위한 도구로 캠페인 간 벤치마킹 및 비교를 수행합니다.
  • 고객 지원 부서에서 어떤 유형의 콘텐츠가 반응을 이끄는지 분석하여 언제, 어떻게 응답할지 결정합니다.
  • 내 플랫폼에서 게시된 콘텐츠의 분석을 표시합니다.  
Engagement API는 2016년에 출시되었으며 대규모로 심층적인 참여 지표를 제공한 최초의 X API였습니다. Engagement API는 사용이 간편하며 고객이 프로세스를 자동화할 수 있도록 해줍니다. 다음은 예시 통합을 설명하는 사례 연구입니다: 이제 Engagement API의 ‘이유’를 살펴보았으니, 기술적 세부 사항을 파고들어 보겠습니다.

​
참여 API 통합

API 소개
Engagement API는 JSON으로 인코딩된 요청을 받아 JSON으로 인코딩된 참여 지표로 응답하는 간단한 RESTful API입니다. 요청은 세 가지 주요 요소로 구성됩니다(자세한 내용은 링크 참조):
  • Post ID 배열
  • 관심 있는 지표 유형 배열. 유형에는 ‘impressions’, ‘retweets’, ‘hashtag_clicks’, ‘user_follows’ 등이 포함됩니다.
  • Engagement 그룹화. API 응답에서 참여 데이터를 어떻게 배열할지 지정하는 JSON 구조입니다.
많은 경우 Engagement 유형과 그룹화는 요청 간 비교적 일정하며, Post ID만 변경됩니다. Engagement API는 세 가지 엔드포인트를 제공합니다:
  • Totals - 게시물에 대한 총 참여 수를 제공합니다. 일부 지표는 모든 게시물에 대해 제공되며, 일부는 최근 90일에 대해서만 제공됩니다.
  • 28 hour - 최근 28시간의 시계열 참여 지표를 제공합니다.
  • Historical - 2014년 9월 1일 이후 게시된 게시물에 대해 최대 4주 연속의 시계열 참여 지표를 제공합니다.
/totals 엔드포인트는 요청당 최대 250개 게시물의 지표 요청을 지원합니다. /28hour 및 /historical 엔드포인트는 요청당 최대 25개를 지원합니다. Engagement API 접근 방법을 논의한 후, API 요청 작성 과정을 살펴보고 OAuth 개요를 제공하며 기타 기술 리소스 링크를 안내합니다.
API 액세스 받기
이 문서를 읽고 있다면 대부분 이미 Engagement API 액세스를 보유하고 있을 가능성이 높습니다. 그렇지 않다면 Enterprise 계정 관리자에게 문의하시거나 여기에서 Enterprise 액세스를 신청하세요. 첫 단계는 승인된 개발자 계정으로 개발자 포털에 로그인해 X 앱을 생성하는 것입니다. 액세스 권한을 부여하려면 계정 관리자가 이 애플리케이션에 연결된 숫자형 App ID가 필요합니다. 개발자 계정을 신청해야 한다면 여기에서 신청할 수 있습니다.
요청 만들기
좋은 소식은 Engagement API에 요청을 보내는 일이 간단하다는 것입니다. 이번 요청에서는 다음 두 @XDevelopers 게시물에 대해 리포스트, 인용 리포스트, 즐겨찾기, 답글의 총합을 요청해 보겠습니다:
1/ 오늘 우리는 X API 플랫폼의 미래에 대한 비전을 공유합니다https://t.co/XweGngmxlP — Twitter Dev (@TwitterDev) 2017년 4월 6일
당신의 게시물에 대한 게시물을 놓치지 마세요. 이제 iOS에서 댓글이 달린 리포스트를 한곳에서 모두 확인할 수 있습니다. pic.x.com/oanjZfzC6y — X (@X) 2020년 5월 12일
첫 번째 단계는 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별로, 다음 단계에서는 참여 유형별로 나열됩니다. 꽤 간단하죠. OAuth 인증이 처음이라면 다음 섹션을 확인하세요.

​
OAuth로 인증하기

OAuth는 기술 업계에서 널리 사용되는 인증 표준입니다. 이미 OAuth를 사용 중이라면(아마도 다른 X API와 함께) 모든 까다로운 세부사항을 추상화해 주는 언어별 OAuth 패키지를 사용하고 있을 가능성이 큽니다. OAuth가 처음이라면 X API용 OAuth 페이지를 방문하시거나 https://oauth.net에서 자세히 알아보세요. 그다음에는 사용하려는 통합 언어에 맞는 OAuth 패키지를 찾아 시작하시길 권장합니다. 이러한 패키지를 사용하면 일반적으로 인증 과정은 키와 토큰을 설정하고, 어떤 형태의 HTTP 객체를 만든 뒤, 그 객체로 요청을 보내는 흐름을 따릅니다. 예를 들어 Ruby 환경에서는 아래 의사 코드를 통해 Ruby gem ‘oauth’를 사용하여 OAuth 지원 앱을 만들고 POST 요청을 보내는 절차를 보여줍니다: 
require 'oauth'

#JSON 요청 조립 (위와 동일).
request = make_json_request()

#내 앱 컨슈머 키와 시크릿으로 앱 컨슈머 객체를 빌드합니다.
consumer = OAuth::Consumer.new(keys['consumer_key'], keys['consumer_secret'], {:site => 'https://data-api.x.com'})
#권한을 제공하는 계정에서 제공한 토큰으로 사용자 토큰을 빌드합니다. 앱 전용 요청을 수행하는 경우 (권한이 필요하지 않은 게시물을 /totals 엔드포인트로 확인), 이 단계는 건너뛸 수 있습니다.
token = {:oauth_token => keys['access_token'], :oauth_token_secret => keys['access_token_secret']}

#OAuth 지원 앱 객체를 생성합니다.
app = OAuth::AccessToken.from_hash(consumer, token)
#POST 요청을 수행합니다.
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 day - 최근 28일간 ‘owned’ 게시물의 시계열 Engagement 지표를 제공합니다. 요청당 게시물 25개를 지원합니다.
  • Historical - 2014년 9월 1일 이후 게시된 ‘owned’ 게시물에 대해 최대 연속 4주간의 시계열 Engagement 지표를 제공합니다. 요청당 게시물 25개를 지원합니다.  
각 엔드포인트는 고유한 특성이 있습니다. 세 가지 모두를 사용할 계획이든 사용 사례에 가장 알맞은 것을 결정하려는 경우든, 이들 간의 차이를 이해하는 것이 중요합니다. 아래에서는 몇 가지 핵심 개념을 소개하고 세 엔드포인트를 더 자세히 살펴본 뒤, 일반적으로 특정 엔드포인트에 매핑되는 예시 사용 사례를 제시합니다. 이 정보가 세 가지를 모두 더 효율적으로 통합하거나 단일 엔드포인트 중 목적에 가장 적합한 것을 선택하는 데 도움이 되길 바랍니다.  

​
핵심 개념

세 가지 Engagement API 엔드포인트가 제공하는 다양한 기능과 데이터의 차이를 설명하는 데 도움이 되는 핵심 개념이 몇 가지 있습니다.  
노출수 및 참여 지표
노출수는 X 플랫폼에서 특정 게시물이 자연스러운 컨텍스트에서 실제로 화면에 표시된 횟수를 의미합니다. 프로모션 또는 유료 컨텍스트에서 발생한 노출은 포함되지 않습니다. Engagement API 도입 이전에 게시물 노출수는 잠재적 조회수의 지표에 불과했습니다. 작성자 계정과 해당 콘텐츠를 리포스트한 계정의 팔로워 수를 합산하는 방식이었고, 특정 사용자가 실제로 게시물을 보지 않는 일반적인 상황은 반영하지 못했습니다. The impression metrics generated by the Engagement API is an actual measure of the number of times a Post has been rendered for display. If a follower of your account misses your Post, it does not count as an impression. Engagement API는 14개의 고유한 참여 메트릭 유형에 대한 지표를 제공합니다. 각 유형은 사용자가 게시물을 접했을 때 수행할 수 있는 개별 행동을 나타냅니다. 여기에는 리포스트, 좋아요, 댓글 달기, #해시태그·링크·미디어 등 엔티티 클릭, 작성자 팔로우, 작성자 프로필 보기 등이 포함됩니다. 이러한 개별 행동은 모두 단일 참여(Engagements) 메트릭으로 집계됩니다.
소유된 X 콘텐츠와 비소유 X 콘텐츠
Engagement는 소유된 게시물과 비소유 게시물을 명확히 구분합니다. 소유된 게시물은 내 계정에서 게시된 게시물이거나, 해당 게시물의 Engagement 데이터를 요청할 수 있는 권한을 보유한 게시물입니다. 다른 X API와 마찬가지로, 다른 X 사용자/계정이 여러분을 대신해 API 요청을 보낼 수 있도록 해주는 액세스 토큰을 공유받아 권한을 획득합니다. 이러한 토큰을 얻는 일반적인 방법은 ‘Sign in with X’ 프로세스입니다. /totals 엔드포인트는 소유된 게시물과 비소유 게시물 모두에 대한 참여 데이터를 제공합니다. 비소유 게시물의 경우, 게시물 화면에서 공개적으로 확인할 수 있는 Favorite, Retweet, Reply와 같은 참여 지표를 요청할 수 있습니다. 이들 지표와 관련해 Engagement API가 제공하는 가치는 이러한 지표를 자동화된 방식으로 대규모로 조회할 수 있는 능력입니다. 소유된 게시물의 경우 /totals 엔드포인트는 Impression 및 총 Engagement 지표도 제공합니다. /28hr 및 /historical 엔드포인트는 소유된 게시물에 대해서만 지표를 제공하며, 이는 해당 엔드포인트에 요청할 때 사용자 컨텍스트를 함께 전달해야 함을 의미합니다.
총계 및 시계열 참여 데이터
/​totals 엔드포인트는 이름 그대로 각 참여 유형의 총합만 제공합니다. 이 수치는 게시물이 게시된 이후 현재까지의 최신 누계를 나타냅니다. 게시물이 방금 게시된 경우 해당 지표를 반복해서 요청하면 요청할 때마다 이 총계가 자주 변동될 수 있습니다. /​28hr 및 /​historical 엔드포인트는 총합과 시계열 데이터를 모두 제공합니다. 시계열 데이터를 요청할 때 참여 지표는 일간 또는 시간대별 데이터로 집계할 수 있습니다.    /​28hr 및 /​historical 엔드포인트로 시계열 데이터를 요청하는 방법은 engagement groupings 문서를 참조하세요.

​
엔드포인트와 예시 사용 사례

위에서 논의한 특성과 차이점을 고려하면, 각 엔드포인트는 일반적으로 상이한 유형의 사용 사례에 대응합니다. 특정 사용 사례에 가장 적합한 엔드포인트를 선택하는 데 도움이 되도록, 아래에 예시 사용자 진술과 이를 가장 잘 충족하는 엔드포인트를 제시합니다.
/totals
  • 특정 지표 유형(노출수, 참여수, 즐겨찾기, 리트윗, 인용 리트윗, 답글, 동영상 조회수)만 필요합니다.
  • 내가 소유한 게시물뿐 아니라 모든 게시물에 대한 기본 참여 데이터를 조회할 수 있어야 합니다.
  • 경쟁사 대비 성과를 비교하고 싶습니다.
  • 내가 소유하지 않은 게시물을 포함하는 해시태그나 캠페인의 기본 참여 지표를 추적하고 싶습니다.
  • 데이터를 일(day)이나 시간(hour) 단위로 나눌 필요는 없으며, 요청 시점의 현재 합계만 필요합니다.
  • 보고서나 대시보드에 표시할 단일 지표가 필요하며, 데이터를 저장할 계획은 없습니다.
  • 페이지 로드 시점에 데이터를 표시하고 싶으며, 요청하고 응답만 받으면 됩니다.
  • 하루에 수십만에서 수백만 개의 게시물 데이터를 GET으로 조회할 수 있어야 합니다.  
/28hr
  • 17가지 모든 지표 유형에 대한 액세스가 필요합니다.
  • 지난 28시간 내에 게시된 최신 게시물의 데이터를 표시하고 싶습니다.
  • 하루에 한 번 실행되어 필요한 데이터를 가져오는 작업이 있으며, 지난 하루치 데이터만 가져오면 됩니다.
  • 지표를 일(day) 또는 시간(hour) 단위로 분리해 제공받아야 합니다.
  • 대시보드에서 시간(hour) 기준의 활동 시계열 분포를 표시하고 싶습니다.
  • 하루에 수십만 개의 게시물에 대한 높은 수준의 액세스가 필요합니다.
  • 스토리지 기능이 있어 하루에 한 번 데이터를 새로 고치고 누적 합계를 유지할 수 있습니다.  
/historical
  • 17가지 모든 지표 유형에 접근할 수 있어야 합니다.
  • 2014년 9월까지 소급되는 게시물의 과거 데이터를 조회해야 합니다.
  • 캠페인을 비교하는 상세한 과거 분석을 보여주고 싶습니다.
  • 지표를 일 또는 시간 단위로 분리해야 합니다.
  • Engagement API에 대한 높은 수준의 접근은 필요 없으며, 하루에 수백 또는 수천 개의 게시물 데이터만 조회하면 됩니다.

​
Engagement API 핵심 특성

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

​
Engagement API로 인증하기

참고:  API를 사용하기 전에 X가 귀하의 Developer 앱에 대해 Engagement API 액세스를 활성화해야 합니다. 이를 위해 인증에 사용할 App ID를 계정 매니저 또는 기술 지원 팀에 반드시 공유해 주십시오.
Engagement API에는 두 가지 인증 방법이 있습니다: OAuth 1.0a 및 OAuth 2.0 Bearer Token.  OAuth 2.0 Bearer Token(“application-only”라고도 함)을 사용하면 공개적으로 제공되는 참여 지표에 접근할 수 있습니다. 이 인증 방법은 /totals 엔드포인트에 요청을 보낼 때, 공개적으로 조회 가능한 모든 게시물에 대해 즐겨찾기(좋아요), 리트윗, 인용 트윗, 답글, 동영상 조회수의 총합을 가져오는 데 사용할 수 있습니다.  OAuth 1.0a(“user context”라고도 함)을 사용하면 사용자를 대신해 요청을 보내고 해당 사용자에게 속한 비공개 참여 지표에 접근할 수 있습니다.  다음의 경우 이 인증 방법이 필요합니다:
  • /28hr 엔드포인트 및 /historical 엔드포인트로 전송하는 모든 요청
  • 다음 비공개 지표에 대한 접근: 노출수(Impressions), 참여수(Engagements), 미디어 조회수(Media Views), 미디어 참여수(Media Engagements), URL 클릭수(URL Clicks), 해시태그 클릭수(Hashtag Clicks), 상세 확장(Detail Expands), 퍼머링크 클릭수(Permalink Clicks), 앱 설치 시도(App Install Attempts), 앱 열기(App Opens), 이메일 게시물(Email Post), 사용자 팔로우(User Follows), 사용자 프로필 클릭수(User Profile Clicks)
OAuth 1.0a로 요청을 보낼 때는 관심 있는 게시물 또는 보호된 리소스의 소유자인 사용자의 액세스 토큰(액세스 토큰과 시크릿)을 포함해야 합니다. 보호된 사용자 데이터를 요청하면서 올바른 사용자 액세스 토큰을 제공하지 않으면 Engagement API는 403 Forbidden 오류를 반환합니다. Engagement API는 보호된 게시물에 대한 참여 데이터를 가져오는 것을 허용하지 않습니다. 해당 게시물의 소유자를 대신해 인증하더라도 마찬가지입니다. 이를 시도하면 "Tweet ID(s) are unavailable" 메시지와 함께 400 Bad Request 오류가 반환됩니다. 자신의 X 계정(즉, Developer 앱을 소유한 계정)을 대신하여 요청을 보내는 경우, 개발자 포털에서 해당 Developer 앱의 “Keys and 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에서의 활동 성과를 모니터링할 수 있도록 매우 유용한 노출 및 참여 지표를 제공합니다. 당사 데이터에 기반한 마케팅 의사결정을 지속적으로 지원하기 위해 X 전반의 지표와 더 큰 일관성을 제공하는 Engagement API의 최근 변경 사항을 공유합니다.   최근 우리는 Engagement API가 X 분석 대시보드(analytics.x.com)와 동일한 지표 집계 방법론을 사용하도록 현대화하는 변경을 배포했습니다. 새로운 지표를 도입하면서 API 변경으로 인한 영향을 최소화하기 위해 신중하게 접근했으며, 첫 번째 변경 사항 세트는 2017년 10월 9일에 배포되었습니다. 이 변경으로 여러분 또는 고객이 X에서 성과를 모니터링하는 모든 지점 간의 일관성이 개선됩니다. 자세한 변경 사항은 아래를 참조하세요:
MetricChange
engagements전체 참여도에 포함되는 세부 지표를 Post 분석 대시보드와 일치하도록 업데이트했습니다. engagements는 “사람들이 이 게시물과 상호작용한 횟수”를 측정합니다.

동영상이나 GIF 등 미디어가 포함된 게시물의 경우 engagements 지표에는 더 이상 미디어 조회수가 포함되지 않습니다. 미디어 조회수는 이제 새로운 지표인 _media_views_에서 확인할 수 있습니다.
media_clicks*이 지표는 “media_engagements”라는 새로운 지표로 대체되었습니다.
video_views2018년 7월 6일부터 이 지표는 /totals 엔드포인트를 통해 ‘unowned’ 게시물에도 제공됩니다. 즉, 앱 전용 인증을 사용하면 모든 게시물의 동영상 조회수에 접근할 수 있습니다. 

동영상 조회수는 1800일 이내의 항목에 대해서만 요청할 수 있습니다. 1800일보다 오래된 게시물의 동영상 조회수를 요청하면 다음과 같은 응답을 받게 됩니다:

“unsupported_for_video_views_tweet_ids”: [“TWEET_ID”]

참고: video_views는 최소 2초 동안 동영상의 50%가 화면에 노출되어야 한다는 MRC 표준에 기반하므로 media_views와 다를 수 있습니다.

또한 X가 소유·운영하는 플랫폼(모바일 앱 및 웹사이트)에 표시되는 동영상 조회수와 /28hr 및 /historical 엔드포인트를 통해 받는 수치 사이에 불일치가 있을 수 있습니다.

* X 사용자 인터페이스와 /totals 엔드포인트에서 제공되는 동영상 조회수는 해당 동영상이 게시된 모든 게시물을 합산한 집계값을 표시합니다. 즉, UI에 표시되는 지표에는 해당 동영상이 리트윗되거나 별도의 게시물로 재게시된 모든 경우의 조회수가 포함됩니다.
* /28hr 및 /historical 엔드포인트에서 제공되는 동영상 조회수는 여러분이 지표를 조회하는 특정 게시물에서 발생한 조회수만 포함합니다.
media_views동영상, Vine, GIF, 이미지 전반에서 집계된 미디어 조회수(자동 재생 및 클릭)를 모두 포함합니다.

참고: 이미지가 포함된 게시물은 분석 대시보드에 media_views 지표가 표시되지 않지만, Engagement API에서는 반환됩니다.
media_engagements*동영상, Vine, GIF, 이미지 전반에서 미디어에 대한 클릭 수를 포함합니다. 이 지표는 _media_clicks_를 대체합니다.
quote_tweets2020년 7월 7일부터 이 지표는 /totals 엔드포인트를 통해 ‘unowned’ 게시물에도 제공됩니다. 즉, 앱 전용 인증을 사용하면 모든 게시물의 인용 게시물 수에 접근할 수 있습니다.

​
지표 해석하기

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

​
노출수 및 참여 데이터

Engagement API는 오가닉 노출수와 참여 데이터를 제공합니다. 노출수는 특정 게시물이 X 플랫폼에서 오가닉 컨텍스트로 표시된 횟수를 의미합니다. 프로모션 또는 유료 컨텍스트에서 노출되어 발생한 노출수는 포함되지 않습니다. 참여는 특정 게시물에 대해 조회자가 오가닉 및 프로모션 컨텍스트에서 상호작용한 횟수를 의미합니다. 참여에는 리트윗, 좋아요, 답글, URL 클릭, 해시태그 클릭, 멘션 클릭, 미디어 조회 등이 포함되지만 이에 한정되지는 않습니다. 포함되는 전체 참여 액션 목록은 Engagement Data 섹션을 참고하세요.  기본 참여율을 계산하려면 분석 대상 기간 동안 특정 게시물의 총 참여수를 총 노출수로 나누세요. 노출수 및 참여 데이터는 소유 중인 @handle의 게시물이나, 귀하의 애플리케이션에 해당 게시물 세부정보 열람을 승인한 @handle의 게시물에 대해서만 조회할 수 있습니다. 내부적으로 Engagement API는 계약된 @handle 한도 대비 요청된 고유 @handle 수를 추적합니다. 또한 월간 단위로 클라이언트 측에서 @handle 요청 사용량을 함께 추적할 것을 권장합니다.  

​
비디오 지표

X에는 미디어 노출을 나타내는 여러 지표가 있습니다. 첫 번째는 비디오 조회수 지표로, 최소 2초 동안 동영상의 50% 이상이 화면에 노출되어야 한다는 MRC 표준을 따릅니다. 두 번째는 Media Views로, 동영상, Vine, GIF, 이미지 전반에서 자동 재생과 클릭을 포함한 모든 미디어 조회를 합산합니다. 비디오 조회수 지표는 /28hour 및 /historical 엔드포인트를 통해 소유한 게시물에 제공되며, /totals 엔드포인트를 통해 소유하지 않은 모든 게시물에도 제공됩니다.  X 사용자 인터페이스의 비디오 조회수 지표도 동일한 MRC 표준을 사용하지만, X가 소유·운영하는 플랫폼(모바일 앱 및 웹사이트)에 표시되는 비디오 조회수와 다양한 Engagement API 엔드포인트를 통해 수신하는 수치 간에는 차이가 있을 수 있습니다.
  • /totals 엔드포인트와 X 사용자 인터페이스에서 제공되는 비디오 조회수는 해당 비디오가 게시된 모든 게시물 전반의 조회수를 집계해 표시합니다. 즉, /totals로 제공되고 X UI에 표시되는 지표에는 해당 비디오가 다른 게시물에서 리트윗되거나 리포스트된 모든 경우의 조회수가 합산됩니다.
  • /28hour 및 /historical Engagement API 엔드포인트에서 제공되는 비디오 조회수는 여러분이 지표를 조회하는 특정 게시물에서 발생한 조회수만 포함합니다.   
게시 후 1800일이 지난 게시물에 대해서는 비디오 조회수를 제공하지 않습니다. 대신, 1800일이 지난 게시물 목록을 담은 객체를 제공합니다. 요청한 게시물의 다른 모든 지표는 별도의 객체로 계속 제공됩니다. 다음은 예시 응답입니다: 
{
  "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 그룹화

그룹화는 반환된 참여 지표를 원하는 방식으로 정리할 수 있게 합니다. 요청당 최대 3개의 그룹화를 포함할 수 있습니다. 지표는 다음 값 중 하나 이상으로 그룹화할 수 있습니다: 세 엔드포인트 모두에서 지원:
  • tweet.id
  • engagement.type  
/28hr 및 /historical 엔드포인트는 시계열 지표를 제공할 수 있으므로 다음을 지원합니다:
  • engagement.day
  • engagement.hour
그룹화는 순차적으로 적용되므로 group_by 값의 순서를 바꾸면 원하는 결과 형식을 변경할 수 있습니다. group_by 값이 네 개인 그룹화는 다음 두 가지 형식 중 하나에서만 지원됩니다: 
"group_by": [
    "tweet.id",
    "engagement.type",
    "engagement.day",
    "engagement.day"
  ]
또는 
"group_by": [
    "engagement.type",
    "tweet.id",
    "engagement.day",
    "engagement.day"
]
예를 들어 메트릭 유형의 총계를 산출하려면, 요청에 다음 “groupings” 사양을 포함하세요(요청 구성에 대한 자세한 내용은 API Reference 페이지를 참고하세요): 
{
  "engagement_types": [
    "favorites",
    "replies",
    "retweets"
  ],
  "groupings": {
    "Grand Totals": {
      "group_by": [
        "engagement.type"
      ]
    }
  }
}
이 그룹화를 사용하면 Engagement API의 JSON 응답에 메트릭 유형별 총합을 담은 루트 수준의 “Grand Totals” 속성이 포함됩니다: 
{
  "총합계": {
    "favorites": "12",
    "replies": "2",
    "retweets": "2"
  }
}
단일 게시물에 대해 게시물 id별로 그룹화된 4시간 시계열 지표를 생성하려면 다음 그룹화 사양을 요청에 포함합니다: 
{
  "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, 다음으로 지표 유형별로 구분된 지표와 해당 시간별 시계열이 포함됩니다. 
{
  "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"
        }
      }
    }
  }
}

​
자주 묻는 질문

엔터프라이즈

​
Engagement API

Engagement API는 엔터프라이즈 구독을 통해 제공됩니다. 영업팀과 연락하려면 이 양식을 작성해 주세요.
계약에 Engagement API와 함께 사용할 수 있는 고유 핸들 수에 대한 한도가 포함된 경우, 내부 X 시스템은 Engagement API로 조회된 게시물을 소유한 인증된 사용자의 수를 집계합니다. 고객도 클라이언트 측에서 이 고유 수를 관리해야 합니다. 현재 Engagement API의 @handle 사용량을 확인할 수 있는 전용 사용량 API나 UI는 없습니다. 계약된 수보다 더 많은 @handle이 요청되더라도 시스템이 즉시 차단하지는 않습니다. 청구 월 말에 조회된 고유 @handle 수를 계약된 수와 비교하며, 계약 조건에 따라 초과 사용료가 청구됩니다.
현재 Engagement API의 @handle 사용량을 확인할 수 있는 전용 사용량 API나 UI는 없습니다. 계약된 수보다 더 많은 @handle이 요청되더라도 시스템이 즉시 차단하지는 않습니다. 청구 월 말에 조회된 고유 @handle 수를 계약된 수와 비교하며, 계약 조건에 따라 초과 사용료가 청구됩니다.페이로드에 반환되는 engagements 메타데이터 필드가 다양한 참여 지표 합계와 일치하지 않습니다. 왜 그런가요?이는 정상입니다. engagements 메타데이터 필드는 API가 반환하는 개별 참여 지표의 총합과 항상 일치하지 않을 수 있습니다. 페이로드에서 별도로 분리되어 제공되지 않는 추가 참여가 engagements 메타데이터 필드에 포함될 수 있기 때문입니다. 즉, 다양한 참여 지표의 합을 모두 더해도 페이로드의 engagements 메트릭 필드 값과 같지 않을 수 있습니다.engagements 메타데이터 필드는 게시물에서 발생한 모든 클릭이나 상호작용으로 이해하시면 됩니다.  페이로드 응답의 url_clicks 필드가 숫자를 반환하는데, 해당 게시물에는 URL이 없습니다. 어떻게 그럴 수 있나요?해시태그처럼 다른 페이지로 연결되는 요소가 포함된 게시물의 경우, 사용자가 이를 클릭하면 URL 클릭으로 집계될 수 있습니다.  
특정 게시물의 참여 데이터를 가져오지 못하는 이유는 다음과 같을 수 있습니다:
  • 제3자를 대신해 데이터를 가져오기 위해 사용하는 인증 토큰 기준으로, 요청한 게시물 ID가 제공 대상이 아닌 경우
  • /totals 엔드포인트에 대해 요청한 게시물 ID가 90일 이내가 아니어서 노출수 또는 참여 지표를 반환할 수 없는 경우
  • 요청한 게시물 ID가 더 이상 제공되지 않는 경우(대부분 삭제되었거나 다른 이유로 공개적으로 접근할 수 없음)
이러한 경우에 받을 수 있는 다양한 오류 메시지를 확인해 주세요.
Engagement API에 요청을 보낼 때 응답 헤더에 포함된 x-per-minute-limit 및 x-per-minute-remaining 정보를 사용해 사용량을 모니터링할 수 있습니다.x-per-minute-limit은 할당량을, x-per-minute-remaining은 남은 호출 수를 알려줍니다.

​
오류 문제 해결 가이드

Engagement API용 인증 지침을 반드시 확인하세요.
[
    Your account could not be authenticated. Reason: Unknown Authorization Type;
]
/totals 엔드포인트로 인증을 시도할 때는 access token이나 secret을 사용하지 마세요. 이러한 토큰을 포함한 상태에서, 해당 토큰과 연관되지 않은 게시물의 콘텐츠를 가져오려고 하면 다음과 같은 오류가 발생할 수 있습니다:
[
    Forbidden to access tweets: 1054424731825229824;
]

​
아직 원하는 정보를 못 찾으셨나요?

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

​
API 참고 문서

​
POST insights/engagement

​
메서드

메서드설명
POST /insights/engagement/totals게시물 모음에 대한 총 노출수와 참여수를 조회합니다.
POST /insights/engagement/historical2014년 9월 1일까지 소급하여, 최대 4주 기간의 게시물 모음에 대한 노출수와 참여수를 조회합니다.
POST /insights/engagement/28hr지난 28시간 동안의 게시물 모음에 대한 노출수와 참여수를 조회합니다.

​
인증

Engagement API는 HTTPS 사용을 요구하며, User Context와 Application-Only OAuth를 모두 지원합니다. Engagement API에 대한 대부분의 요청은 3-Legged OAuth(사용자 컨텍스트의 특정 버전)를 필요로 합니다. 이는 Twitter 계정 매니저로부터 Engagement API 액세스가 등록·승인된 앱의 consumer key와 secret, 그리고 게시물 소유자의 액세스 토큰과 액세스 토큰 시크릿을 사용해 엔드포인트를 호출해야 함을 의미합니다. 다음 요청에는 이 유형의 OAuth가 필요합니다:
  • 소유한 게시물로 제한되는 Impressions 및 Engagements 메트릭 유형을 얻기 위한 /totals에 대한 모든 요청
  • /28hr에 대한 모든 요청
  • /historical에 대한 모든 요청
일부 Engagement API 요청은 Application-Only OAuth로 수행할 수 있으며, 이 경우 consumer key와 secret 또는 베어러 토큰만 제공하면 됩니다. 다음 요청은 이 유형의 OAuth로 수행할 수 있습니다:
  • 모든 게시물에 대해 가져올 수 있는 Favorites, Replies, Retweets 또는 Video Views 메트릭 유형을 얻기 위한 /totals에 대한 모든 요청
모든 요청을 위해서는 developer.x.com의 앱 관리 콘솔에서 Twitter 앱과 해당 API 키를 설정해야 합니다. 참고: developer.x.com에서 Twitter 계정으로 로그인한 경우, 기존 Twitter apps는 Twitter app dashboard에서 조회 및 편집할 수 있습니다. 앱을 설정한 후에는 Engagement API에 요청을 보낼 수 있도록 앱 ID가 계정 담당자의 승인을 받아야 합니다. 액세스 토큰은 “현재 사용자”를 나타내는 데 사용되어야 하며, 다른 사용자를 대신하여 수행되는 요청은 유효한 토큰으로 서명해야 합니다. OAuth 서명 베이스 문자열을 준비하기 전에 URL과 POST 본문에서 예약 문자 인코딩이 올바르게 적용되었는지 확인하세요. OAuth 시작 방법에 대한 자세한 내용은 다음 링크를 참조하세요:

​
POST /insights/engagement/totals

이 totals 엔드포인트는 한 번에 최대 250개의 게시물 모음에 대해 현재 총 노출 수와 참여 수를 조회할 수 있도록 합니다.
요청 메서드HTTP POST
URLhttps://data-api.x.com/insights/engagement/totals
콘텐츠 유형application/json
압축Gzip. Gzip 압축을 사용하여 요청하려면 연결 요청에 Accept-Encoding 헤더를 전송하십시오.
헤더는 다음과 같아야 합니다:

Accept-Encoding: gzip
POST 형식요청은 게시물 ID 모음과 원하는 그룹화를 포함하는 JSON 객체를 본문으로 하는 POST 요청으로 전송할 수 있습니다. POST는 tweets, engagements, groupings 객체가 포함된 배열로 형식화됩니다. 각 요청에는 최대 250개의 게시물 ID가 포함될 수 있습니다.

POST 본문 예시는 다음과 같습니다:


{
“tweet_ids”: [
“게시물 ID 1”,
“게시물 ID 2”,
“게시물 ID 3”
],
“engagement_types”: [
“impressions”,
“engagements”,
“favorites”,
“quote_tweets”
],
“groupings”: {
“그룹화 이름”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}
게시물 ID참여 데이터를 쿼리할 게시물의 게시물 ID를 포함하는 배열입니다. 인증하는 @handle이 생성한 게시물에 대한 데이터만 요청할 수 있습니다. 요청당 최대 250개의 게시물이 포함될 수 있으며, 게시물 ID는 문자열로 표현되어야 합니다.
참여 유형쿼리할 참여 지표 유형을 포함하는 배열입니다. Totals 엔드포인트는 다음 참여 유형만 지원합니다: impressions, engagements, favorites, retweets, quote_tweets, replies, video_views.
/totals 엔드포인트는 지난 90일 이내에 생성된 게시물에 대한 impressions 및 engagements와 모든 게시물에 대한 favorites, retweets, quote_tweets, replies, video_views를 검색하는 기능을 지원합니다.
그룹화Engagement API의 결과는 필요에 가장 적합하도록 다양한 그룹으로 반환될 수 있습니다. 요청당 최대 3개의 그룹화를 포함할 수 있습니다.

각 그룹화에 대해 애플리케이션에서 이 그룹화 유형을 더 쉽게 참조할 수 있도록 사용자 정의 그룹화 이름을 정의할 수 있습니다.

그룹화 이름을 정의한 후 tweet.id 및/또는 engagement.type으로 그룹화하도록 선택할 수 있습니다.

그룹화는 순차적으로 적용되므로 group_by 값의 순서를 변경하여 원하는 결과 형식을 변경할 수 있습니다. 게시물 ID와 지표 유형별로 구분된 지표를 표시하는 그룹화 예시는 다음과 같습니다:


“groupings”: {
“내 그룹화 이름”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
POST 크기 제한한 번에 최대 250개의 게시물 ID에 대해 요청할 수 있습니다.
응답 형식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”
}
}
}
사용 불가능한 게시물 ID사용 불가능한 게시물 ID(예: 삭제된 게시물)가 포함된 쿼리의 경우, 사용 가능한 모든 게시물 ID에 대한 적절한 데이터가 반환되며, 사용 불가능한 게시물 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 hour 엔드포인트는 지난 28시간 동안 최대 25개 게시물 모음에 대한 노출 수와 참여 수를 조회할 수 있습니다. 또한 이 엔드포인트는 지원되는 모든 개별 지표에 대해 지표를 요청할 수 있도록 합니다. 지원되는 지표의 전체 목록은 Metric Availability를 참조하세요.
요청 메서드HTTP POST
URLhttps://data-api.x.com/insights/engagement/28hr
콘텐츠 유형application/json
압축Gzip. Gzip 압축을 사용하여 요청하려면 연결 요청에 Accept-Encoding 헤더를 전송하십시오.
헤더는 다음과 같아야 합니다:

Accept-Encoding: gzip
POST 형식요청은 게시물 ID 모음과 원하는 그룹화를 포함하는 JSON 객체를 본문으로 하는 POST 요청으로 전송할 수 있습니다. POST는 tweets, engagements, groupings 객체가 포함된 배열로 형식화됩니다. 각 요청은 최대 25개의 게시물 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”
]
}
}
}
게시물 ID참여 데이터를 쿼리할 게시물의 게시물 ID를 포함하는 배열입니다. 인증하는 @handle이 생성한 게시물에 대한 데이터만 요청할 수 있습니다. 28시간 엔드포인트는 요청당 최대 25개의 게시물을 지원하며, 게시물 ID는 문자열로 표현되어야 합니다.
참여 유형쿼리할 참여 지표 유형의 배열입니다.

28시간 엔드포인트의 경우 impressions, engagements 및 모든 개별 참여 유형이 지원되는 지표입니다. 지원되는 참여 지표의 전체 목록은 참여 데이터를 참조하십시오.
그룹화참여 API의 결과는 사용자의 요구에 가장 적합하도록 다양한 그룹으로 반환될 수 있습니다. 요청당 최대 3개의 그룹화를 포함할 수 있습니다.

각 그룹화에 대해 애플리케이션에서 이 그룹화 유형을 더 쉽게 참조할 수 있도록 사용자 정의 그룹화 이름을 정의할 수 있습니다. 그룹화 이름을 정의한 후 다음 값 중 하나 이상으로 그룹화하도록 선택할 수 있습니다:
tweet.id
engagement.type
engagement.day
engagement.hour
그룹화는 순차적으로 적용되므로 group_by 값의 순서를 변경하여 원하는 결과 형식을 변경할 수 있습니다. 게시물 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개의 게시물 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”
]
}
}
}‘
응답 예시{
“start”: “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”
}
}
}
}
}
사용 불가능한 게시물 ID사용 불가능한 게시물 ID(예: 삭제된 게시물)가 포함된 쿼리의 경우, 사용 가능한 모든 게시물 ID에 대한 적절한 데이터가 반환되며, 사용 불가능한 게시물 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

이 히스토리컬 엔드포인트는 최대 25개 게시물로 구성된 컬렉션에 대해 최대 4주 기간의 노출 수와 참여 수를 조회할 수 있습니다. 현재 2014년 9월 1일 이전 데이터는 API로 요청할 수 없습니다. 또한 히스토리컬 엔드포인트를 통해 지원되는 모든 개별 지표에 대한 메트릭을 요청할 수 있습니다. 지원되는 메트릭의 전체 목록은 Metric Availability를 참조하세요.
요청 메서드HTTP POST
URLhttps://data-api.x.com/insights/engagement/historical
콘텐츠 타입application/json
압축Gzip. Gzip 압축을 사용하여 요청하려면 연결 요청에 Accept-Encoding 헤더를 전송하십시오.
헤더는 다음과 같아야 합니다:

Accept-Encoding: gzip
POST 형식요청은 게시물 ID 모음과 원하는 그룹화를 포함하는 JSON 객체를 본문으로 하는 POST 요청으로 전송될 수 있습니다. POST는 tweets, engagements, groupings 객체가 포함된 배열로 형식화됩니다. 각 요청은 최대 25개의 게시물 ID를 가질 수 있습니다. 각 요청은 최대 4주 기간의 사용자 지정 시작 및 종료 날짜로 지정할 수 있습니다.


{
“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.day”
]
}
}
}
시작 및 종료 날짜요청의 일부로 start 및 end 값을 사용하여 사용자 지정 시작 및 종료 날짜를 지정할 수 있습니다. 기간이 4주를 초과하지 않는 시작 및 종료 날짜를 지정해야 합니다. 현재 가능한 가장 오래된 시작 날짜는 2014년 9월 1일입니다. 미래의 종료 날짜는 지원되지 않습니다. 시작 및 종료 날짜가 제공되지 않으면 API는 기본적으로 직전 4주로 설정됩니다.

Engagement API에서 데이터를 반환할 수 있는 가장 낮은 세분성은 시간 단위입니다. 시간 경계에 정확히 맞지 않는 시작 또는 종료 값으로 요청하는 경우 요청은 가장 가까운 포괄적 시간으로 기본 설정됩니다. 예를 들어, “start”:“2015-07-01T12:24:00Z” 및 “end”:“2015-07-10T08:37:00Z”로 요청하면 “start”:“2015-07-01T12:00:00Z”,“end”:“2015-07-10T09:00:00Z”로 기본 설정됩니다.
게시물 ID참여 데이터를 쿼리할 게시물의 게시물 ID를 포함하는 배열입니다. 인증하는 @handle이 생성한 게시물에 대한 데이터만 요청할 수 있습니다. 4주 기록 엔드포인트는 요청당 최대 25개의 게시물을 지원하며 게시물 ID는 문자열로 표현되어야 합니다.
참여 유형쿼리할 참여 지표 유형을 포함하는 배열입니다.

4주 기록 엔드포인트의 경우 impressions, engagements 및 모든 개별 참여 유형이 지원되는 지표입니다. 지원되는 참여 지표의 전체 목록은 참여 데이터를 참조하십시오.

참고: 현재 2015년 9월 15일 이전에 수행된 쿼리에 대해 0으로 표시되는 세 가지 지표가 있습니다: favorites, replies, retweets.
그룹화Engagement API의 결과는 사용자의 요구에 가장 적합하도록 다양한 그룹으로 반환될 수 있습니다. 요청당 최대 3개의 그룹화를 포함할 수 있습니다.

각 그룹화에 대해 애플리케이션에서 이 그룹화 유형을 더 쉽게 참조할 수 있도록 사용자 지정 그룹화 이름을 정의할 수 있습니다. 그룹화 이름을 정의한 후 다음 값 중 하나 이상으로 그룹화하도록 선택할 수 있습니다:
tweet.id
engagement.type
engagement.day
engagement.hour
그룹화는 순차적으로 적용되므로 group_by 값의 순서를 변경하여 원하는 결과 형식을 변경할 수 있습니다. 게시물 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개의 게시물 ID에 대해 요청할 수 있습니다.
응답 형식JSON. 요청의 헤더는 응답에 대한 JSON 형식을 지정해야 합니다.
속도 제한액세스 수준에 따라 계약에 명시된 대로 분당 속도 제한이 적용됩니다.
요청 예시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”
}
}
}
사용 불가능한 게시물 ID사용 불가능한 게시물 ID(예: 삭제된 게시물)가 포함된 쿼리의 경우, 사용 가능한 모든 게시물 ID에 대한 적절한 데이터가 반환되며, 사용 불가능한 게시물 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
}
}
}

​
응답 코드

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

​
오류 메시지

다양한 상황에서 Engagement API는 상황별 오류 메시지를 반환하며, 애플리케이션은 이를 처리할 수 있어야 합니다. 아래 표에는 이러한 오류 메시지의 일반적인 예와 해석 방법이 포함되어 있습니다. 많은 경우 Engagement API는 추가 정보를 담은 200 OK 응답의 일부로 특정 오류 메시지와 함께 이용 가능한 데이터의 부분 결과를 반환할 수 있다는 점에 유의하십시오.
Error MessageDescription
"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일 이내가 아니므로, impressions 또는 engagements 지표를 반환할 수 없습니다.
"errors":["Forbidden to access tweets: *TWEET_IDS*"]제3자를 대신해 데이터를 조회할 때 사용 중인 인증 토큰 기준으로, 요청한 Tweet ID에 대한 접근이 허용되지 않습니다.