Pular para o conteúdo principal

​
Visão geral

O campo metrics permite que desenvolvedores acessem metrics de engajamento públicas e privadas para objetos de Post e mídia. As métricas públicas estão disponíveis para qualquer pessoa com uma conta de desenvolvedor, enquanto as métricas privadas podem ser acessadas a partir de contas próprias/autorizadas (definição abaixo). As métricas incluem a contagem total de impressões, Retweets, Quote Tweets, likes, respostas, visualizações de vídeo, quartis de visualização de vídeo e cliques em URL e em link de perfil para cada Post especificado na solicitação. Também é possível visualizar a distribuição das métricas obtidas em contexto orgânico ou promovido, caso o Post tenha sido promovido como um Ad. As métricas públicas podem ser solicitadas com autenticação App-only Token. As métricas não públicas podem ser solicitadas apenas para Posts próprios/autorizados, o que significa que os desenvolvedores precisam se autenticar usando autorização em contexto de usuário com OAuth 2.0 ou OAuth 1.0a. Métricas não públicas, orgânicas e promovidas estão disponíveis apenas para Posts criados nos últimos 30 dias.

​
Terminologia

  • Conta autorizada: Uma conta do X que autorizou seu X developer app ao conceder acesso a essa conta (qualquer app permission level permitirá acesso às metrics de Post).
  • Conta de propriedade: Uma conta do X vinculada ao seu X developer app.
  • Public metrics: Totais disponíveis para qualquer pessoa no X, como o número de likes e o número de Retweets.
  • Non-public metrics: Totais não disponíveis para visualização pública no X, como o número de impressões e quartis de visualização de vídeo. Requer autenticação com contexto de usuário via OAuth 2.0 ou OAuth 1.0a.
  • Organic metrics: Agrupamento de public e non-public metrics atribuídas a um context orgânico (publicado e visualizado de maneira regular). Requer autenticação com contexto de usuário via OAuth 2.0 ou OAuth 1.0a.
  • Promoted metrics: Agrupamento de public e non-public metrics atribuídas a um context promovido (publicado ou visualizado como parte de uma campanha de Ads). Requer autenticação com contexto de usuário via OAuth 2.0 ou OAuth 1.0a e que o Post tenha sido promovido em um Ad.

​
Métricas disponíveis

MétricaRepresentações na APIDescrição
Impressionsdata.non_public_metrics.impression_count, data.organic_metrics.impression_count, data.promoted_metrics.impression_countContagem de quantas vezes o Post foi exibido (não exclusivo por usuário). Uma visualização é contabilizada se qualquer parte do Post estiver visível na tela. Requer autenticação com Contexto de Usuário do OAuth 1.0a.
Retweetsdata.public_metrics.retweet_count, data.organic_metrics.retweet_count, data.promoted_metrics.retweet_countContagem de quantas vezes o Post foi Retweetado. Não inclui Quote Tweets (“Retweets with comment”). Para obter o total de “Retweets e comentários” exibido nos clientes do X, some retweet_count e quote_count.
Quote Tweetsdata.public_metrics.quote_countContagem de quantas vezes o Post foi Retweetado com um novo comentário (mensagem). Não há Quote Tweets em contexto pago; portanto, todos os Quote Tweets são orgânicos.
Likesdata.public_metrics.like_count, data.organic_metrics.like_count, data.promoted_metrics.like_countContagem de quantas vezes o Post recebeu like. O campo public_metrics retorna a contagem total de likes tanto de contextos orgânicos quanto pagos, para manter a consistência com as contagens exibidas publicamente no X.
Repliesdata.public_metrics.reply_count, data.organic_metrics.reply_count, data.promoted_metrics.reply_countContagem de quantas vezes o Post recebeu resposta. O campo public_metrics retorna a contagem total de respostas tanto de contextos orgânicos quanto pagos.
URL Link Clicksdata.non_public_metrics.url_link_clicks, data.organic_metrics.url_link_clicks, data.promoted_metrics.url_link_clicksContagem do número de vezes que um usuário clica em um link de URL ou em um cartão de prévia de URL em um Post. Requer autenticação com Contexto de Usuário do OAuth 1.0a.
User Profile Clicksdata.non_public_metrics.user_profile_clicks, data.organic_metrics.user_profile_clicks, data.promoted_metrics.user_profile_clicksContagem do número de vezes que um usuário clica em partes de um Post: nome de exibição, nome de usuário, foto do perfil. Requer autenticação com Contexto de Usuário do OAuth 1.0a.
Video viewsincludes.media.public_metrics.view_count, includes.media.organic_metrics.view_count, includes.media.promoted_metrics.view_countContagem de quantas vezes o vídeo incluído no Post foi visualizado. Este é o número de visualizações de vídeo agregado em todos os Posts nos quais o vídeo em questão foi publicado. Requer a expansão de mídia expansions=attachment.media_keys.
Video view quartilesincludes.media.non_public_metrics.playback_0_count, includes.media.non_public_metrics.playback_25_count, includes.media.non_public_metrics.playback_50_count, includes.media.non_public_metrics.playback_75_count, includes.media.non_public_metrics.playback_100_countNúmero de usuários que assistiram até cada quartil de um vídeo. Requer autenticação com Contexto de Usuário do OAuth 1.0a e a expansão de mídia expansions=attachment.media_keys.

​
Solicitando metrics

​
Métricas públicas

Na solicitação a seguir, estamos pedindo métricas públicas do Post e do vídeo anexado, usando os seguintes fields e expansions. Certifique-se de substituir $BEARER_TOKEN pelo seu próprio Bearer Token.
  • tweet.fields=public_metrics
  • expansions=attachments.media_keys&media.fields=public_metrics

​
Exemplo de requisição

curl 'https://api.x.com/2/tweets?ids=1204084171334832128&tweet.fields=public_metrics&expansions=attachments.media_keys&media.fields=public_metrics' --header 'Authorization: Bearer $BEARER_TOKEN'

​
Métricas privadas (métricas não públicas e orgânicas)

A solicitação a seguir requisita métricas não públicas, com detalhes adicionais sobre métricas orgânicas, para o Post e o vídeo anexado. Como esses fields são privados e não estão disponíveis para visualização pública no X, a solicitação requer autenticação em contexto de usuário via OAuth 2.0 ou OAuth 1.0a. Consulte nosso guia para gerar a assinatura OAuth 1.0a necessária abaixo.
  • tweet.fields=non_public_metrics,organic_metrics
  • expansions=attachments.media_keys&media.fields=non_public_metrics,organic_metrics

​
Exemplo de requisição

curl 'https://api.x.com/2/tweets/1204084171334832128?tweet.fields=non_public_metrics,organic_metrics&media.fields=non_public_metrics,organic_metrics&expansions=attachments.media_keys' --header 'authorization: OAuth oauth_consumer_key="CONSUMER_API_KEY", oauth_nonce="OAUTH_NONCE", oauth_signature="OAUTH_SIGNATURE", oauth_signature_method="HMAC-SHA1", oauth_timestamp="OAUTH_TIMESTAMP", oauth_token="ACCESS_TOKEN", oauth_version="1.0"'

​
Exemplo de resposta

{
  "data": {
    "attachments": {
      "media_keys": ["13_1204080851740315648"]
    },
    "id": "1263145271946551300",
    "non_public_metrics": {
      "impression_count": 956,
      "url_link_clicks": 9,
      "user_profile_clicks": 34
    },
    "organic_metrics": {
      "impression_count": 956,
      "like_count": 49,
      "reply_count": 2,
      "retweet_count": 9,
      "url_link_clicks": 9,
      "user_profile_clicks": 34
    },
    "text": "teste"
  },
  "includes": {
    "media": [
      {
        "media_key": "13_1204080851740315648",
        "non_public_metrics": {
          "playback_0_count": 0,
          "playback_100_count": 1,
          "playback_25_count": 2,
          "playback_50_count": 1,
          "playback_75_count": 1
        },
        "organic_metrics": {
          "playback_0_count": 0,
          "playback_100_count": 1,
          "playback_25_count": 2,
          "playback_50_count": 1,
          "playback_75_count": 1,
          "view_count": 1
        },
        "type": "video"
      }
    ]
  }
}
⌘I