Monitoring

Monitor an account

POST /v1/monitor/targets targets:write

Start monitoring an account, named by screen_name or by user_id. If we already know it you are subscribed immediately; otherwise we resolve it on X first and you get 202. An account X told us in the last ten minutes cannot be monitored (it does not exist, is suspended, or its posts are protected) is refused at once with 404. Without event_types every event type your key allows is delivered for it; with it, only those types. Sending event_types for an account you already monitor replaces its choice; leaving it out keeps it. See Choosing event types.

Request body

Body field	Type	Meaning
`screen_name`	string	Handle without `@`; 1–15 letters, digits or underscores. Send this or `user_id`
`user_id`	string	The account's numeric X id, instead of `screen_name`. An id never changes, so prefer it when you have it
`event_types`	string[]	Only these event types are delivered for this account; omit or send `[]` for all. `search.match` belongs to keywords and is refused here

response

201 subscribed, 200 already subscribed, 202 queued for resolution; all three carry a Location header pointing at the detail endpoint. A 202 for an account that failed earlier carries last_failure (reason, failed_at). 404 user_not_found, user_suspended or user_protected: X told us in the last ten minutes that this account cannot be monitored; details.failed_at says when.

Status: 201, 200, 202, 400, 402, 403

request

curl -X POST https://api.xsignalfeed.com/v1/monitor/targets \
  -H "Authorization: Bearer xsf_your_key" -H "Content-Type: application/json" \
  -d '{"screen_name": "elonmusk", "event_types": ["followers.verified.add"]}'

response · 201 / 200

{
  "status": "subscribed",
  "state": "subscribed",
  "id": "44196397",
  "screen_name": "elonmusk",
  "name": "Elon Musk",
  "event_types": [
    "followers.verified.add"
  ],
  "event_types_all": false
}
{
  "status": "queued",
  "state": "queued",
  "screen_name": "newaccount",
  "user_id": null,
  "event_types": [],
  "event_types_all": true,
  "note": "target will be resolved and placed shortly; poll GET /v1/monitor/targets/{screen_name}"
}