Getting News By Keyword in Realtime

This chapter is a brief tutorial on how to use the X Activity API to get news emerging on X in realtime, filtered by keywords of your choice.

Subscribing to News

You create a subscription the same way as in Subscribing to public events: POST /2/activity/subscriptions with event_type, filter, and webhook_id.

This time, you'll use the news.new event type, and you'll specify a keyword in the filter field instead of a user id:

xurl --auth app /2/activity/subscriptions -X POST -d '{
  "event_type": "news.new",
  "filter": {
    "keyword": "Tesla"
  },
  "tag": "Tesla trends",
  "webhook_id": "YOUR_WEBHOOK_ID"
}'

Success Response

{
  "data": {
    "subscription": {
      "created_at": "2025-10-07T05:31:56Z",
      "event_type": "news.new",
      "filter": {
        "keyword": "Tesla"
      },
      "subscription_id": "1146654567674912769",
      "tag": "Tesla news",
      "updated_at": "2025-10-07T05:31:56Z",
      "webhook_id": "YOUR_WEBHOOK_ID"
    }
  },
  "meta": {
    "total_subscriptions": 1
  }
}

Getting News Events

If you specified a webhook, you'll start to see news with a headline containing your keyword as trends are generated.

{
  "data": {
    "event_uuid": "1985729017958244577",
    "filter": {
      "keyword": "spacex"
    },
    "event_type": "news.new",
    "tag": "spacex news",
    "payload": {
      "headline": "This is some spacex news breaking on X",
      "summary": "Spacex just launched a rocket"
    }
  }
}

Duplicate News

If you specified multiple subscriptions for news, and a single news event matches multiple subscriptions, it may be delivered multiple times. Use event_uuid to deduplicate at the application layer.

{
  "data": {
    "event_uuid": "1985729017958244577",
    "filter": { "keyword": "jack" },
    "event_type": "news.new",
    "tag": "jack news",
    "payload": {
      "headline": "New Jersey Gubernatorial Election Between Jack Ciattarelli and Mikie Sherrill",
      "summary": "Voters in New Jersey head to the polls..."
    }
  }
}

{
  "data": {
    "event_uuid": "1985729017958244577",
    "filter": { "keyword": "mikie" },
    "event_type": "news.new",
    "tag": "mikie news",
    "payload": {
      "headline": "New Jersey Gubernatorial Election Between Jack Ciattarelli and Mikie Sherrill",
      "summary": "Voters in New Jersey head to the polls..."
    }
  }
}

Use Cases

Setting up a news feed using the X Activity API is a perfect way to integrate a live feed of events you care about into your application.