twitr-sh Monitors API
The Monitors API from twitr-sh — 3 operation(s) for monitors.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/twitr-sh:twitr-sh-monitors-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: twitr.sh Monitors API
version: 1.0.0
contact:
email: support@twitr.sh
description: 'Pay-per-call X/Twitter data API for AI agents: single-object reads, tweet/user search, timelines, lists, communities, bulk extractions (23 tools, async with downloadable datasets), real-time account/keyword monitors (prepaid hours; events via free polling or signed webhooks), giveaway draws, trend radar, and an AI tweet composer. No signup — the wallet is the account; an optional API key (Authorization: Bearer) spends a prepaid card balance instead. Payment via x402 v2 (USDC on Base/Solana) and MPP (USDC on Tempo). Per-result reads use x402 upto on Base only: the 402 quotes a maximum, empty results cost $0, and non-empty calls have a $0.0024 minimum. Volume tools bill per returned item against a mandatory resultsLimit; extractions and monitors settle before dispatch.'
x-guidance: 'All tools are POST /api/tools/{tool} and return 402 with payment options on first call (Base upto only for per-result reads; fixed operations can offer exact x402 and MPP); pay and retry to receive data. Volume tools (x_search, x_timeline, x_lists, x_communities non-info kinds, followers-you-know) REQUIRE resultsLimit (integer 1–10000) — you are billed per returned item and the cap is enforced upstream. x_extract is async: it returns {snapshot_id, status_url}; poll GET /api/snapshots/{id} (free, SIWX) until status=ready for a download_url. x_monitor is PREPAID by the hour: it stops at expires_at unless extended — extend early, never expect refunds on deletion; events flow to GET /api/monitors/{id}/events (free, SIWX) or your registered webhook (/api/webhooks, signed with X-Twitr-Signature). draws, x_extract and x_monitor require an Idempotency-Key header. radar + compose are flat floor-priced. GET /api/snapshots and GET /api/monitors (SIWX) list the wallet''s history for free. Errors are RFC 9457 Problem bodies (components.schemas.Problem) with machine-actionable `retryable` and `hint` fields — retryable:true means retry the SAME request unchanged after a backoff; x402 reads settle after success; prepaid operations can fail after payment. Alternative to per-call payment: send `Authorization: Bearer tw_live_…` (an API key created at /dashboard) and each call is charged to that account''s prepaid USD balance at the same prices — per-result reads charge only returned records; the free SIWX endpoints accept the same key.'
servers:
- url: https://twitr.sh
tags:
- name: Monitors
paths:
/api/monitors:
get:
operationId: list_my_monitors
summary: List monitors owned by the caller's wallet
description: Every real-time monitor this wallet has paid for, with prepaid-expiry state. Free — identity via SIWX (CAIP-122). Create/extend monitors via the paid endpoint POST /api/tools/x_monitor.
tags:
- Monitors
x-guidance: Call when the user asks about their monitors or remaining prepaid hours. Free, SIWX-signed. To keep a monitor running, extend it via /api/tools/x_monitor BEFORE expires_at.
security:
- siwx: []
responses:
'200':
description: Monitors owned by the signing wallet.
content:
application/json:
schema:
type: object
properties:
wallet:
type: string
count:
type: integer
monitors:
type: array
items:
type: object
properties:
monitor_id:
type: string
pattern: ^mn_[a-z0-9]+$
type:
type: string
enum:
- account
- keyword
target:
type: string
description: Monitored username or search query.
event_types:
type: array
items:
type: string
status:
type: string
enum:
- active
- expired
- deleted
created_at:
type: integer
description: Unix ms.
expires_at:
type: integer
description: Unix ms — end of the prepaid window. The monitor stops here unless extended.
remaining_seconds:
type: integer
hours_purchased:
type: integer
paid_total_usd:
type: string
required:
- monitor_id
- type
- target
- status
- expires_at
required:
- wallet
- count
- monitors
'402':
description: Identity Required — sign SIWX and retry.
/api/monitors/{id}:
get:
operationId: get_monitor
summary: Monitor detail
tags:
- Monitors
security:
- siwx: []
parameters:
- name: id
in: path
required: true
schema:
type: string
pattern: ^mn_[a-z0-9]+$
responses:
'200':
description: Monitor detail + events_url + extend hint.
content:
application/json:
schema:
type: object
properties:
monitor:
type: object
properties:
monitor_id:
type: string
pattern: ^mn_[a-z0-9]+$
type:
type: string
enum:
- account
- keyword
target:
type: string
description: Monitored username or search query.
event_types:
type: array
items:
type: string
status:
type: string
enum:
- active
- expired
- deleted
created_at:
type: integer
description: Unix ms.
expires_at:
type: integer
description: Unix ms — end of the prepaid window. The monitor stops here unless extended.
remaining_seconds:
type: integer
hours_purchased:
type: integer
paid_total_usd:
type: string
required:
- monitor_id
- type
- target
- status
- expires_at
'402':
description: Identity Required — sign SIWX and retry.
'403':
description: Signing wallet doesn't own this monitor.
'404':
description: Monitor unknown or expired out of retention.
delete:
operationId: delete_monitor
summary: Delete a monitor immediately
description: Stops the monitor now. Remaining prepaid hours are NOT refunded.
tags:
- Monitors
security:
- siwx: []
parameters:
- name: id
in: path
required: true
schema:
type: string
pattern: ^mn_[a-z0-9]+$
responses:
'200':
description: Deleted. `{ok, monitor_id, status}`.
'402':
description: Identity Required — sign SIWX and retry.
'403':
description: Signing wallet doesn't own this monitor.
'404':
description: Monitor unknown.
'503':
description: Teardown briefly contended — retry in a few seconds.
/api/monitors/{id}/events:
get:
operationId: poll_monitor_events
summary: Poll a monitor's events (free)
description: 'Events captured by this monitor, oldest→newest. Pass the last event id you processed as `after` to receive only newer events. Bounded retention (500 events / 24h per monitor) — register a webhook for guaranteed delivery. Rate limit: 60 reads/minute per wallet.'
tags:
- Monitors
x-guidance: Poll at most once per second, ideally on user demand. Persist next_cursor between polls. For push delivery instead, register a webhook at POST /api/webhooks.
security:
- siwx: []
parameters:
- name: id
in: path
required: true
schema:
type: string
pattern: ^mn_[a-z0-9]+$
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: after
in: query
schema:
type: string
description: Last event id you processed — response contains strictly newer events.
- name: type
in: query
schema:
type: string
enum:
- tweet.new
- tweet.reply
- tweet.retweet
- tweet.quote
- tweet.media
- tweet.link
- tweet.poll
- tweet.mention
- tweet.hashtag
- tweet.longform
- profile.avatar.changed
- profile.banner.changed
- profile.name.changed
- profile.username.changed
- profile.bio.changed
- profile.location.changed
- profile.url.changed
- profile.verified.changed
- profile.protected.changed
- profile.pinned_tweet.changed
- profile.unavailable.changed
- monitor.expired
- monitor.deleted
responses:
'200':
description: Event page.
content:
application/json:
schema:
type: object
properties:
monitor_id:
type: string
events:
type: array
items:
type: object
properties:
id:
type: string
type:
type: string
occurred_at:
type: string
received_at:
type: string
source:
type: object
data:
type: object
required:
- id
- type
- occurred_at
- data
next_cursor:
type: string
has_more:
type: boolean
retention:
type: object
required:
- monitor_id
- events
- has_more
'402':
description: Identity Required — sign SIWX and retry.
'403':
description: Signing wallet doesn't own this monitor.
'429':
description: Polling too fast — includes Retry-After.
components:
securitySchemes:
siwx:
type: apiKey
in: header
name: SIGN-IN-WITH-X
description: Sign-In-With-X (CAIP-122). Base64-encoded CAIP-122 payload signed by the caller's wallet. Server recovers the signer address cryptographically; any client-supplied wallet parameter is ignored.
bearerKey:
type: http
scheme: bearer
description: Optional API key (tw_live_…) created in the dashboard. Paid tools charge the key owner's prepaid USD balance instead of an on-chain payment; free endpoints accept it in place of SIWX.
publicRead:
type: apiKey
in: query
name: _public
description: No-op placeholder. This endpoint requires no authentication; the scheme exists so validators that want a named security reference on public operations have one to point at.
x-ux-hints: Confirm with the user before any call that quotes above $0.10 or requests resultsLimit >= 500. Never spin a background poll loop — when the user asks progress on an extraction, call /api/snapshots/{id} (free, SIWX). Send Idempotency-Key with paid calls so a dropped response is replayed from cache (10 min) instead of re-running. Wallet history is free — use it when the user asks 'what have I extracted?'.
x-service-info:
categories:
- data
- social
- search
- developer-tools
docs:
homepage: https://twitr.sh
apiReference: https://twitr.sh/openapi.json
llms: https://twitr.sh/llms.txt
x-discovery:
ownershipProofs: []