X lists

The x_list kind collects the posts of one X list through the X API v2. Each post becomes a Record; an edit becomes a new Version, and a post deleted or made protected on X is withdrawn. The kind comes from the first-party x-list plugin. Collect from a source covers what every kind shares.

X bills API reads per post returned. Check your plan’s prices and caps in the X Developer Console; Quivr’s max_reads_per_day below is a guard, the console’s spend limit is the hard stop.

Prerequisites

An X developer app and its app-only bearer token, able to read the list. For real-time mode, also the app’s consumer secret, and a plan that includes Filtered Stream and webhooks.
The list’s numeric id, from its URL: https://x.com/i/lists/<list_id>. An app-only token cannot read another account’s private list.
A credential_key in Quivr’s configuration, since the instance stores a secret.
The x-list plugin pinned. In the local stack it points at a local fake of the X API, so use a real deployment to collect real posts.

Create an instance

curl -s -X POST "$QUIVR_API_URL/v0/connectors" -H "Authorization: Bearer $QUIVR_API_KEY" \
  -H "Content-Type: application/json" -d @- <<EOF | jq '{connector_id, health: .health.state}'
{
  "idempotency_key": "watchlist",
  "corpus_id": "$CORPUS_ID",
  "source_namespace": "x-watchlist",
  "kind": "x_list",
  "config": {"list_id": "1234567890123456789", "max_reads_per_day": 5000},
  "schedule": {"interval_seconds": 120},
  "credential": {"secret": {"bearer_token": "<bearer token>"}}
}
EOF

Config field	Default	Meaning
`list_id`	required	The numeric list id
`backfill_since`	none	Also collect posts created since this instant, at most 7 days before the first poll
`max_reads_per_day`	none	Stop polling for new posts once this many posts were read in the UTC day, at least 100
`recheck_window_seconds`	`86400`	How long collected posts are checked for deletion, 1 hour to 7 days
`recheck_interval_seconds`	`600`	How often that check runs, at least 60 seconds

Collection starts at the first poll. Each run reads the list newest first, down to where the previous run stopped, at most 1,000 posts.

What each post becomes

The Record Key is the id of the original post, so every edit of a post is a Version of the same Record. The body Part holds the post’s full text. Quoted, replied-to and reposted posts become Relations to other Records of the same Source Namespace. The connector.x_list extension holds the author, dates, language, entities, media references and the post URL; media files are not downloaded.

Deletions

X’s developer policy requires removing content deleted or made protected on X. The plugin rechecks recent posts every recheck_interval_seconds and withdraws those that are gone, so a deletion is reflected within about 12 minutes with the defaults. It tracks at most 2,000 posts.

Posts older than recheck_window_seconds are not rechecked. If you must honour a removal request for an older post, withdraw its Record yourself with POST /v0/records/withdrawals.

Spend

health.usage estimates the posts read today and yesterday (UTC), counted as X deduplicates them. Roughly, each new post is read once, the top page of the list costs at most about 100 extra reads a day, and each post in the recheck window is read about once more per day. A shorter interval lowers latency without multiplying cost. When max_reads_per_day is reached, polling stops until the next UTC day with last_error.code daily_read_cap_reached; deletion rechecks continue.

Real-time mode

With webhooks on, posts from the list’s members arrive within seconds; polling stays on as the fallback. You need:

public_url in Quivr’s configuration: the address where X reaches the API, such as https://quivr.example.com. Each instance’s webhook address is <public_url>/v0/connector-webhooks/<connector_id>, shown as webhook_url.
The x-list plugin pinned on the api processes too, since the API relays each delivery to it.
The consumer secret deposited with the token: {"bearer_token": "…", "consumer_secret": "…"}.
"webhook": {"enabled": true} in the instance’s config. Set max_rules and max_rule_length to your plan’s limits.

The plugin turns the list’s members into Filtered Stream rules tagged quivr:<connector_id>, registers the webhook and keeps both in step at each resync. health.push.state is pending until then, active once deliveries arrive, and degraded with an error when polling had to take over. A post seen both ways is one Record with one Version. Turning the mode off leaves the rules and the webhook at X until you delete them in the developer console.

Health codes

`last_error.code`	Health	Meaning
`unauthorized`, `forbidden`	`access_error`	X refused the token, or the app may not read the list
`list_not_found`	`access_error`	The list id does not exist
`credits_depleted`	`access_error`	Credits or the spend limit are exhausted in the X console
`rate_limited`	unchanged	X answered 429; the next run waits for the reset
`daily_read_cap_reached`	unchanged	`max_reads_per_day` was reached
`source_unavailable`	unchanged	Network error, timeout or 5xx
`invalid_config`	unchanged	`backfill_since` is more than 7 days before the first poll

Get started

Plugins

Guides

Prerequisites

Create an instance

What each post becomes

Deletions

Spend

Real-time mode

Health codes

​Prerequisites

​Create an instance

​What each post becomes

​Deletions

​Spend

​Real-time mode

​Health codes

Prerequisites

Create an instance

What each post becomes

Deletions

Spend

Real-time mode

Health codes