X Pay-Per-Use Sources

Summary

X is now viable as an AgentInbox host without committing to the old subscription-package model.

The official docs now describe the X API as pay-per-usage with upfront credits, per-endpoint pricing, 24-hour deduplication, and a monthly cap on pay-per-use Post reads. That is enough to support a first x host in AgentInbox, but we should be selective about which stream kinds we expose first.

Tracking issue:

• #162 research: phase an x host around pay-per-use source kinds

The strongest first source is still a shared public stream:

• filtered_stream

The most credible follow-up pull sources are:

• recent_search
• full_archive_search
• user_posts
• user_mentions

User-bound or webhook-heavy sources are possible, but should come later:

• home_timeline
• liked_posts
• bookmarks
• account_activity
• activity

We should not model raw webhooks as a source kind. In the X docs, webhooks are delivery infrastructure used by specific products such as Account Activity, X Activity, and Filtered Stream webhook delivery.

What The Official Docs Confirm

As of 2026-04-19, the official docs state:

• X API uses pay-per-usage pricing with no monthly subscription commitment beyond prepaid credits.
• Pricing is endpoint-specific and current rates live in the Developer Console, not in the public docs.
• Pay-per-use usage is tracked at the app level with a monthly cap of 2 million Post reads.
• Billable resources are deduplicated within a 24-hour UTC window.
• The usage API can be queried programmatically to track consumption.

This matters for AgentInbox because it means an X host can be designed around:

• shared app credentials at the host level
• stream-specific checkpoints and cursors
• explicit cost-aware stream choices
• runtime-visible usage telemetry for operational guardrails

Important Product Implications

1. X Fits The Host + Stream Model Well

The current repository direction is already moving toward:

• provider host
• concrete stream under that host
• agent-specific subscription on top

X is a strong fit for this structure because one developer app can back many different feed shapes with different polling or streaming semantics.

Recommended host kind:

• x

Recommended high-level auth variants under the host:

• app-only bearer auth for public read/search/stream sources
• user-context auth for personalized or private feeds
• webhook registration secrets for push-based activity products

2. Cost Is Part Of Source Design

For X, source selection is not just a transport question. It is also a cost question.

The same user need can often be implemented in multiple ways:

• filtered_stream for near-real-time public matching
• recent_search for low-complexity polling over the last 7 days
• account_activity for owned-account push events

Those options have different:

• latency
• operational complexity
• authentication requirements
• billing behavior

So the source catalog should expose deliberate stream kinds instead of a generic x_query abstraction.

Candidate Stream Kinds

P0: public shared streams

filtered_stream

Why it should be first:

• closest fit to AgentInbox's ingress model
• near-real-time delivery
• one shared rule set can serve many agents through subscriptions
• official docs explicitly show pay-per-use support

Operational shape:

• one SourceStream per rule set or managed stream definition
• host owns app credentials
• stream owns rules, connection state, reconnect policy, and checkpoint
• subscriptions filter on normalized metadata after ingestion

Expected stream config:

• rules
• expansions
• tweetFields
• userFields
• mediaFields
• optional delivery mode: persistent connection first, webhook later if needed

Recommended normalized metadata:

• postId
• authorId
• authorUsername
• conversationId
• lang
• isReply
• isRetweet
• matchedRules
• createdAt

Design note:

Because pay-per-use filtered stream allows one connection and up to 1,000 rules in the public docs, this is best treated as a shared host-managed stream rather than a per-agent connector.

recent_search

Why it belongs in the catalog:

• simple pull-based source
• lower integration risk than persistent streaming
• good for low-frequency monitors and scheduled triage
• available to all developers, so it is a safe baseline

Operational shape:

• poll GET /2/tweets/search/recent
• checkpoint by newest seen Post ID or timestamp window
• map search query to a shared stream key

Best use cases:

• keyword tracking
• brand or repo mention polling
• scheduled research feeds
• fallback when filtered_stream is unnecessary

full_archive_search

Why it should exist but not be first:

• powerful for backfill and historical bootstrap
• pay-per-use explicitly includes full-archive search
• more likely to be cost-sensitive than recent search

Recommended role:

• first-class source kind only if we need durable historical ingestion
• otherwise keep as a backfill helper for future stream bootstrap workflows

P1: public user-oriented pull streams

user_posts

Why it is useful:

• direct way to follow one account's authored Posts
• simple checkpoint semantics with since_id
• natural fit for "watch this account" subscriptions

Good first-party use cases:

• follow product or org accounts
• monitor release channels
• watch owned bot accounts

user_mentions

Why it is useful:

• more direct than broad search for owned-account mention workflows
• natural fit for agent inboxes that need to respond to mentions
• simpler and cheaper than full account activity if mention monitoring is the only requirement

Important limit:

• official docs describe the mentions timeline as capped to the most recent 800 mentions

list_posts

Possible but lower priority:

• appears in usage tracking docs as a billable tracked endpoint
• good fit for curated watchlists
• not required for a strong v1 X host

I would keep this out of the first implementation unless a concrete product need appears.

P2: user-context personalized streams

home_timeline

This is a real candidate source, but not an early one.

Reasons to defer:

• requires user authentication
• personalized feed semantics are runtime-sensitive and less reusable across agents
• less aligned with the "shared source before private connector" principle

This should only be added when we explicitly want personal-assistant style inboxing of a user's own X feed.

liked_posts

Possible as a user-bound pull source:

• can represent "watch what this account liked"
• more niche than posts or mentions
• likely lower reuse value than public feeds

This should not be in the first rollout.

bookmarks

Possible but should be treated as private, user-scoped data:

• requires user-context auth
• only useful for a narrow personal workflow
• fits AgentInbox technically, but not as an early shared-source priority

This is a valid later source, especially for "saved for later" assistant workflows.

P3: push products with webhook complexity

account_activity

Why it is attractive:

• real-time owned-account events
• richer than mentions or posts alone
• includes Posts, mentions, replies, follows, likes, DMs, and more

Why it should not be first:

• webhook registration and CRC validation add operational complexity
• pay-per-use docs show a very small self-serve limit: 3 unique subscriptions and 1 webhook
• this is better for owned-account automation than for broad public monitoring

Product fit:

• strong later source for account-linked agent assistants
• poor first source for a shared multi-agent public monitoring layer

activity

Why it is interesting:

• more event-oriented than timeline/search sources
• supports persistent stream and webhook delivery
• can cover profile, follow, spaces, DM, chat, and news events

Why it is risky:

• it is operationally more specialized than the source shapes we need first
• it pulls AgentInbox toward event-bus complexity before we validate core X usage

This should stay behind filtered_stream and account_activity.

What We Should Not Model As Sources

These do not look like primary AgentInbox source kinds:

• raw webhooks
• write operations such as like, unlike, bookmark, or post creation
• single-object lookup endpoints such as post lookup or user lookup

Reason:

• webhooks are a transport used by real products, not a domain source on their own
• write actions belong on DeliveryHandle or provider-specific operations
• one-off lookup endpoints are helpers, not long-lived ingress streams

Recommended Stream Catalog

Recommended x host stream kinds:

Recommended Delivery And Normalization Strategy

For the first x host, we should keep the normalization boundary narrow.

Shared envelope fields should include:

• provider = x
• streamKind
• nativeId
• occurredAt
• deliveryHandle when reply or follow-up is possible

Source-specific payloads should remain source-specific.

Examples:

• filtered_stream and search/timeline sources can emit normalized Post items with source-specific raw payload preserved
• account_activity should preserve activity-type groupings instead of forcing everything into a fake universal message schema
• activity should preserve the event name and filtered user identity

This keeps AgentInbox on its boundary:

• ingress, routing, activation, delivery handle capture

Not:

• X-specific workflow interpretation

Recommended Rollout

Phase 1

Implement:

• x host
• filtered_stream
• recent_search

Why:

• validates shared-host architecture
• gives both real-time and polling modes
• covers the highest-value public monitoring use cases

Phase 2

Add:

• user_posts
• user_mentions
• optional full_archive_search for backfill/bootstrap

Why:

• account-specific monitoring becomes straightforward
• mention-based agent workflows become possible without webhook complexity

Phase 3

Evaluate:

• account_activity
• activity
• home_timeline
• bookmarks

Why:

• these are either user-private, webhook-heavy, or operationally specialized

Risks And Open Questions

1. Public Pricing Is Incomplete

Official docs confirm pay-per-use exists, but they do not publish a stable public per-endpoint rate card. Current rates live in the Developer Console.

Implication:

• source admission should assume pricing can change without docs diffs
• we should expose cost guidance in source docs, not hardcode price math into the product model

2. There Is Documentation Ambiguity Around Webhook Availability

The generic Webhooks API docs present webhook infrastructure as a shared layer, while product pages vary in how they describe pay-per-use versus enterprise availability.

Implication:

• before implementing account_activity or activity, verify access in a real pay-per-use app instead of trusting docs alone

3. The Reported 2026-04-20 Price Drop Was Not Independently Verified Here

During this research pass, I confirmed the current official pay-per-use model, but I did not find a public official doc page that explicitly states a 2026-04-20 price reduction date.

Implication:

• treat the pricing model as confirmed
• treat the exact 2026-04-20 change details as still needing console or announcement verification

Recommendation

Create an x host, but keep the first implementation narrow:

• first ship filtered_stream
• pair it with recent_search
• add user_posts and user_mentions next
• defer webhook-heavy and user-private sources until the first public sources are stable

This aligns with the repository boundary:

• shared source hosting first
• clear delivery and activation semantics
• no premature drift into personal runtime behavior or provider-specific workflow logic

Official References

• X pricing: https://docs.x.com/x-api/getting-started/pricing
• X usage and billing: https://docs.x.com/x-api/fundamentals/post-cap
• Filtered stream: https://docs.x.com/x-api/posts/filtered-stream/introduction
• Search overview: https://docs.x.com/x-api/posts/search/introduction
• Timelines overview: https://docs.x.com/x-api/posts/timelines/introduction
• Timelines integration guide: https://docs.x.com/x-api/posts/timelines/integrate
• Bookmarks: https://docs.x.com/x-api/posts/bookmarks/introduction
• Likes: https://docs.x.com/x-api/posts/likes/introduction
• Account Activity: https://docs.x.com/x-api/account-activity/introduction
• X Activity: https://docs.x.com/x-api/activity/introduction
• Webhooks: https://docs.x.com/x-api/webhooks/introduction