메인 콘텐츠로 건너뛰기
X API v2 엔드포인트에는 응답의 각 객체에서 필요한 데이터만 선택할 수 있도록 해주는 매개변수 집합인 필드가 제공됩니다. 기본적으로 게시물 객체는 id와 text 필드만 반환하며, 2022년 9월 29일 이후에 생성된 게시물의 경우 edit_history_tweet_ids 필드도 포함됩니다. 게시물의 생성일이나 공개 지표가 필요하다면 tweet.fields 매개변수로 요청해야 합니다. 이를 통해 사용 사례에 따라 필요한 필드만 선택적으로 요청하여 맞춤화를 높일 수 있습니다. 예를 들어, 요청에 다음 쿼리 문자열을 포함합니다: ?tweet.fields=created_at,public_metrics 각 객체에는 해당 객체와 연관된 필드를 명시적으로 요청하기 위한 고유한 매개변수가 있습니다. 현재 사용 가능한 필드 매개변수는 다음과 같습니다: 주로 특정 객체를 반환하는 엔드포인트를 사용할 때는 해당 객체에 맞는 필드 매개변수를 사용하고, 필요한 필드를 쉼표로 구분한 목록으로 지정하여 응답에서 해당 필드를 반환받으세요.

​
예시

GET /tweets/search/recent 엔드포인트를 사용하는 경우, 응답에는 주로 Tweet 객체가 포함됩니다. fields 매개변수를 지정하지 않으면 기본값인 id와 text만 반환됩니다. 응답에 포함된 게시물의 공개 지표를 받고 싶다면 요청에 tweet.fields 매개변수를 포함하고, 값으로 public_metrics를 설정하세요. 요청은 다음과 같은 형태입니다. 이 요청을 사용하려면 $BEARER_TOKEN을 베어러 토큰으로 바꾼 뒤, 사용하는 명령줄 도구로 전송하세요. 
curl --request GET \
  --url 'https://api.x.com/2/tweets/search/recent?query=from%3Atwitterdev&tweet.fields=public_metrics' \
  --header 'Authorization: Bearer $BEARER_TOKEN'
터미널에서 이 요청을 보내면 반환되는 각 게시물에 다음 필드가 포함됩니다: 
{
   "data": {
       "id": "1263150595717730305",
       "public_metrics": {
           "retweet_count": 12,
           "reply_count": 14,
           "like_count": 49,
           "quote_count": 7
       },
       "text": "새로운 트윗 설정을 보셨나요? 👀\n\nAPI에서 이러한 기능을 어떻게, 왜 사용하실지 알려주세요. 자세한 내용을 확인하시고 의견을 남겨주세요👇\nhttps://t.co/RtMhhfAcIB https://t.co/8wxeZ9fJER"
   }
}
엔드포인트가 반환하는 기본 객체와 연관된 보조 객체에서 특정 필드 집합을 가져오려면 추가로 expansions 매개변수를 포함해야 합니다. 예를 들어 앞서와 동일한 GET search/tweets/recent 엔드포인트를 사용하면서 작성자의 프로필 설명을 조회하려는 경우, 요청에 expansions=author_id와 user.fields=description을 함께 전달해야 합니다. 아래는 해당 요청의 예시입니다. 이 요청을 직접 시도하려면 명령줄 도구에 붙여넣기 전에 $BEARER_TOKEN을 Bearer Token으로 교체했는지 확인하세요. 
  curl --request GET \
  --url 'https://api.x.com/2/tweets/search/recent?query=from%3Atwitterdev&tweet.fields=public_metrics&expansions=author_id&user.fields=description' \
  --header 'Authorization: Bearer $BEARER_TOKEN'
요청에 이를 지정하면 전달되는 각 게시물에는 다음 필드가 포함되며, 관련 user object의 기본 필드와 지정한 필드는 includes 내에 반환됩니다. user object는 tweet.author_id와 users.id 필드를 매칭하여 해당 게시물과 다시 매핑할 수 있습니다. 
{
  "data": [
    {
      "id": "1263150595717730305",
      "author_id": "2244994945",
      "text": "새로운 트윗 설정 보셨나요? 👀\n\nAPI에서 이 기능을 어떻게, 왜 사용하실지 알고 싶습니다. 자세한 내용을 확인하고 의견을 들려주세요👇\nhttps://t.co/RtMhhfAcIB https://t.co/8wxeZ9fJER",
      "public_metrics": {
        "retweet_count": 12,
        "reply_count": 13,
        "like_count": 51,
        "quote_count": 7
      }
    }
  ],
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "username": "TwitterDev",
        "description": "#TwitterDev 팀의 목소리이자 #TwitterAPI 관련 업데이트, 뉴스, 이벤트에 대한 공식 소스입니다.",
        "name": "Twitter Dev"
      }
    ]
  }
}
상위 수준 필드(public_metrics)를 지정하는 경우 특정 하위 필드(예: public_metrics.retweet_count)를 개별적으로 요청할 수 없습니다. 상위 수준 필드를 지정하면 모든 하위 필드가 함께 반환됩니다. 요청 가능한 모든 필드는 각 엔드포인트의 API 레퍼런스 페이지에 있는 매개변수 표에 정리되어 있습니다. 전체 필드 목록은 객체 모델에서 확인할 수 있습니다. 해당 엔드포인트의 기본 리소스가 아닌 객체의 필드를 함께 받아보려면, 필드와 함께 expansions 매개변수를 사용하십시오.