X Tracker
Follow X accounts in real time, organize them in lists, and research tweets for token deploys.
The X Tracker is an admin-only workspace that streams posts, follows and profile changes from a set of X accounts, so an operator can react to a tweet and deploy a token from it. One shared session tracks one set of accounts for every admin; each admin keeps their own lists (named subsets of those accounts) and their own settings document.
The live feed is a server-sent event stream. Saved tweets fill the feed on load. Around it, research endpoints relay third-party services through the backend: Frontrun for X search and profile reports, FxTwitter for single tweets, and Serper for Google image search, plus name/ticker suggestions and image analysis used by the deploy flow.
All endpoints require an admin account. The web app shows the page as X Tracker at /tracker.
- GET
/tracker/stream - GET
/tracker/handles - POST
/tracker/handles - DEL
/tracker/handles/{handle} - GET
/tracker/tweets - GET
/tracker/settings - PUT
/tracker/settings - GET
/tracker/lists - POST
/tracker/lists - PATCH
/tracker/lists/{list_id} - DEL
/tracker/lists/{list_id} - GET
/tracker/frontrun/search - GET
/tracker/frontrun/profile/{handle}/{report} - GET
/tracker/frontrun/old-username/{handle} - GET
/tracker/frontrun/credits - POST
/tracker/suggest - POST
/tracker/vision - GET
/tracker/images - GET
/tracker/fx/{tweet_id}
The Tracked handle object
An X account followed by the shared tracker session.
Attributes
-
handlestringX handle, lowercase, without@. -
displayNamestring | nullAccount display name. -
isActivebooleanWhether the session is currently tracking the account. -
twitterUserIdstring | nullNumeric X user ID as a string.
The Tracker list object
A named subset of the tracked accounts, shown as its own feed. Lists belong to the caller.
Attributes
-
idstringUnique identifier. -
namestringList name. -
handlesarray<string>Handles in the list. -
positionintegerSort position; the app orders lists by it. -
iconstring | nullIcon name from the tracker's icon set. -
colorstring | nullColor as#rrggbb.
The Saved tweet object
A tweet event stored by the tracker: the realtime payload as received, with its delivery time and suggestions.
Attributes
-
eventobjectRaw realtime payload (thedof a streameventmessage). -
received_atintegerTime the backend received the event, in Unix milliseconds. -
deletedbooleanWhether the tweet was deleted since. -
suggestionsarray<object> | nullSuggestions for the tweet;nulluntil they are made.
The Suggestion object
A token name and ticker proposed for a tweet.
Attributes
-
namestringToken name. -
symbolstringTicker. -
imagestring | nullImage URL to use, ornull.
Stream tracker events
/tracker/stream Opens a server-sent event stream of the shared tracker session.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
The response is text/event-stream. Events are separated by a blank line (\n\n); the client keeps only data: lines, strips the prefix, joins multi-line data with \n, and parses the result as JSON. Each message has a type:
status: session state, withstatus,error,latencyandsession.event: one realtime event ind.d.eventistwitter.post.new,twitter.post.update,twitter.following.new,twitter.following.removed,twitter.follower.new,twitter.profile.updateortwitter.tweet.deleted;d.task_info.handlenames the tracked account andd.datacarries the event data.handles: the tracked set changed; reload List tracked accounts.suggestions: name/ticker suggestions ready fortweet_id.lagged:skippedevents were dropped.
The SDK makes a raw fetch with the bearer token and returns the Response; the caller reads and closes the body. On 401 or 403 the app stops and reports that the tracker is restricted to admins. On any other failure or end of stream it reconnects with exponential backoff capped at 30 seconds.
Parameters
No parameters.
Returns 200 OK · text/event-stream
A stream of data: events, each a JSON message.
-
typeenumMessage type.Possible valuesstatuseventhandlessuggestionslagged -
statusenumOnstatus: state of the upstream session.Possible valuesidleconnectingauthenticatingconnectedreconnectingerror -
errorstring | nullOnstatus: error message, if any. -
latencynumber | nullOnstatus: latency reported by the session. -
sessionobject | nullOnstatus: session details.Child attributes 3
-
modulesarray<string>Modules enabled on the session. -
handlesinteger | nullAccounts tracked. -
maxHandlesinteger | nullMaximum accounts the session can track.
-
-
dobjectOnevent: the raw realtime payload.Child attributes 7
-
eventstringEvent name, e.g.twitter.post.new. -
event_idstringEvent identifier. -
event_timeintegerEvent time in Unix milliseconds. -
task_infoobject{ handle }of the tracked account. -
dataobjectEvent data: the tweet, the followed account, the profile change or the deleted tweet. -
replayedbooleanThe event is a replay; the app does not notify for it. -
delayedbooleanThe event arrived late.
-
-
tweet_idstringOnsuggestions: the tweet the suggestions are for. -
suggestionsarray<object>Onsuggestions: Suggestion objects. -
skippedintegerOnlagged: number of events skipped. The app ignores this message.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 403 | forbidden | The caller is not an admin. The web app stops reconnecting on this status, as it does on 401. Call it with an admin account's session. |
| 422 | upstream_failure | The server has no Xanguard key, so there is no session to stream. Set XANGUARD_API_KEY on the server, or retry later. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.tracker.stream(signal) src/lib/proxima/endpoints/tracker.ts
List tracked accounts
/tracker/handles Lists the X accounts followed by the shared tracker session.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
The SDK returns the handles array.
Parameters
No parameters.
Returns 200 OK · application/json
Returns a list of Tracked handle objects.
-
handlesarray<object>Tracked handle objects.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
| 422 | upstream_failure | The server has no Xanguard key, or the Xanguard API failed. Set XANGUARD_API_KEY on the server, or retry later. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.tracker.handles() src/lib/proxima/endpoints/tracker.ts
Track an account
/tracker/handles Adds an X account to the shared tracker session.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry A repeat answers 409 once the account is tracked; List tracked accounts shows the current set.
The web app normalizes input before sending: it strips a leading @ and an x.com or twitter.com URL prefix, drops anything after /, ? or #, and lowercases. The SDK returns the stored handle. Bulk import sends one request per handle.
Body parameters application/json
-
handlestring RequiredX handle, without@.
Returns 200 OK · application/json
-
handlestringHandle as stored.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | handle does not reduce to an X handle of 1 to 50 letters, digits or _. Send @name, name or an x.com profile link. |
| 400 | bad_request | Xanguard refused the handle, with its own message. Bulk import skips it and continues. |
| 403 | forbidden | The tracking limit of the Xanguard plan is reached, with Xanguard's own message. Bulk import stops here. Stop tracking an account with Stop tracking an account first. |
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
| 404 | not_found | Xanguard does not know this X account. Bulk import skips it and continues. Check the handle on X. |
| 409 | conflict | The account is already tracked. Bulk import skips it and continues. Nothing to do: the account is already tracked. |
| 422 | upstream_failure | The server has no Xanguard key, or the Xanguard API failed. Set XANGUARD_API_KEY on the server, or retry later. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.tracker.addHandle(handle) src/lib/proxima/endpoints/tracker.ts
Stop tracking an account
/tracker/handles/{handle} Removes an X account from the shared tracker session.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry A repeat after a success may answer an error relayed from Xanguard; List tracked accounts shows the current set.
Path parameters
-
handlestring RequiredX handle, without@.Exampledemo_trader
Returns 200 OK · application/json
The web app does not read the response body.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | handle is not a valid X handle. Send @name, name or an x.com profile link. |
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
| 422 | upstream_failure | The server has no Xanguard key, or the Xanguard API failed. Set XANGUARD_API_KEY on the server, or retry later. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.tracker.removeHandle(handle) src/lib/proxima/endpoints/tracker.ts
List saved tweets
/tracker/tweets Returns stored tweets of the given accounts, used to fill the feed on load.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
The web app requests each viewed account once, in batches of 40 handles with per_handle=100. The SDK returns the tweets array. Saved suggestions are merged into the feed.
Query parameters
-
handlesstring OptionalComma-separated handles.Exampleexamplecaller,demo_trader -
per_handleinteger OptionalMaximum tweets per handle.Example100 -
limitinteger OptionalMaximum tweets in total.
Returns 200 OK · application/json
Returns a list of Saved tweet objects.
-
tweetsarray<object>Saved tweet objects.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 403 | forbidden | The caller is not an admin. The app stays silent instead of showing an error. Call it with an admin account's session. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.tracker.tweets({ handles, perHandle, limit }) src/lib/proxima/endpoints/tracker.ts
Retrieve tracker settings
/tracker/settings Returns the caller's saved tracker settings document.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
The document is free-form JSON owned by the client. The web app stores feed (sound, showMedia, detectVision, maxDepth), per-account prefs, keyword alerts, activeList, defaultList, deploy presets and layout. The SDK returns settings. If loading fails, the app disables saving so stored settings are never overwritten with defaults.
Parameters
No parameters.
Returns 200 OK · application/json
-
settingsobject | nullSaved document, ornullwhen nothing is saved.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.tracker.settings() src/lib/proxima/endpoints/tracker.ts
Save tracker settings
/tracker/settings Replaces the caller's tracker settings document.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry The body replaces the saved settings whole.
The web app saves 800 ms after the last change, and only when the document differs from the last saved copy.
Body parameters application/json
-
settingsobject RequiredThe full settings document.
Returns 200 OK · application/json
The web app does not read the response body.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | settings is not a JSON object. Send settings as an object. |
| 400 | bad_request | settings is larger than 256 KB once serialized. Trim the settings below 256 KB. |
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.tracker.saveSettings(settings) src/lib/proxima/endpoints/tracker.ts
List tracker lists
/tracker/lists Lists the caller's tracker lists.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
The SDK returns the lists array; the app sorts it by position.
Parameters
No parameters.
Returns 200 OK · application/json
Returns a list of Tracker list objects.
-
listsarray<object>Tracker list objects.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.tracker.lists() src/lib/proxima/endpoints/tracker.ts
Create a list
/tracker/lists Creates a tracker list from a name and a set of tracked handles.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Check before retrying A repeat creates a second list with the same name. Look for it in List tracker lists first.
Body parameters application/json
-
namestring RequiredList name. -
handlesarray<string> RequiredHandles in the list. -
iconstring | null OptionalIcon name. -
colorstring | null OptionalColor as#rrggbb.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | The caller already has 50 lists. Free a slot with Delete a list first. |
| 400 | bad_request | name is empty or longer than 40 characters. Send a name of 1 to 40 characters. |
| 400 | bad_request | icon is longer than 32 characters or has characters other than ASCII letters and digits. Send an icon name from the app's icon set, or an empty string to clear it. |
| 400 | bad_request | color is not a #rrggbb hex color. Send a color such as #1d9bf0, or an empty string to clear it. |
| 400 | bad_request | An entry in handles is not a valid X handle. Send @name, name or an x.com profile link. |
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.tracker.createList(name, handles, style) src/lib/proxima/endpoints/tracker.ts
Update a list
/tracker/lists/{list_id} Updates a list's name, handles, position, icon or color.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry
Only the fields sent change. To clear icon or color, send an empty string; the SDK turns a null into "".
Path parameters
-
list_idstring RequiredList ID.Example67744a28-e685-49cd-a56b-803b8e647080
Body parameters application/json
-
namestring OptionalNew name. -
handlesarray<string> OptionalNew set of handles. -
positioninteger OptionalNew sort position. -
iconstring OptionalIcon name, or""to clear. -
colorstring OptionalColor as#rrggbb, or""to clear.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | name is empty or longer than 40 characters. Send a name of 1 to 40 characters. |
| 400 | bad_request | icon is longer than 32 characters or has characters other than ASCII letters and digits. Send an icon name from the app's icon set, or an empty string to clear it. |
| 400 | bad_request | color is not a #rrggbb hex color. Send a color such as #1d9bf0, or an empty string to clear it. |
| 400 | bad_request | An entry in handles is not a valid X handle. Send @name, name or an x.com profile link. |
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
| 404 | not_found | No list with this ID belongs to the caller. Pick a list ID from List tracker lists. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.tracker.updateList(id, patch) src/lib/proxima/endpoints/tracker.ts
Delete a list
/tracker/lists/{list_id} Deletes one of the caller's tracker lists.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry A repeat answers 404 once the list is gone.
Tracked accounts are not affected.
Path parameters
-
list_idstring RequiredList ID.Example67744a28-e685-49cd-a56b-803b8e647080
Returns 200 OK · application/json
The web app does not read the response body.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
| 404 | not_found | No list with this ID belongs to the caller. Pick a list ID from List tracker lists. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.tracker.deleteList(id) src/lib/proxima/endpoints/tracker.ts
Search X posts
/tracker/frontrun/search Searches X through Frontrun, newest first.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Accepts keywords, contract addresses and X operators such as from: or min_faves:. The backend relays Frontrun's envelope unchanged: check status before reading data. The app caches each page for 60 seconds.
Query parameters
-
qstring RequiredSearch query.Example$OTTER min_faves:50 -
page_sizeinteger OptionalResults per page. The app sends20. -
cursorstring OptionalnextCursorfrom the previous page.
Returns 200 OK · application/json
-
statusbooleanfalsewhen Frontrun reports a failure, withmessage. -
messagestringFrontrun's message. -
dataobjectSearch page.Child attributes 2
-
tweetsarray<object>Raw tweets withtweet_id,url,screen_name,text,created_at, engagement counts,user_info,mediaandentities. -
nextCursorstring | nullCursor for the next page, ornull.
-
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | q is empty. Send a search query in q. |
| 401 | — | Frontrun rejected the server's API key. Relayed with Frontrun's own body, without a Proxima code. Check the Frontrun key configured on the server. |
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
| 403 | — | Frontrun rejected the server's API key. Relayed with Frontrun's own body, without a Proxima code. Check the Frontrun key configured on the server. |
| 422 | upstream_failure | The server has no Frontrun key, or the call to Frontrun failed in transit. Set FRONTRUN_API_KEY on the server, or retry later. |
| 429 | — | Frontrun rate limit (60 requests per minute). Relayed with Frontrun's own body, without a Proxima code. Wait a minute before the next Frontrun call. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.tracker.frontrunSearch({ q, pageSize, cursor }) src/lib/proxima/endpoints/tracker.ts
Retrieve an X profile report
/tracker/frontrun/profile/{handle}/{report} Returns a Frontrun report on an X account: its profile, its smart followers, or the contract addresses it posted.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
The data shape depends on report:
info: profile withtwitterId,name,twitterUsername,bio,profilePhoto,followersCount,followingsCountand labels, ornull.smart-followers:{ smartFollowers, totalCount }.tweets-with-ca:{ topUndeletedTweets, topDeletedTweets, undeletedCACount, deletedCACount, undeletedTweetCount, deletedTweetCount }, including tweets that were later deleted.
The app caches each report for 10 minutes so reopening a profile does not spend credits twice.
Path parameters
-
handlestring RequiredX handle, without@.Exampleexamplecaller -
reportenum RequiredReport to fetch.Possible valuesinfosmart-followerstweets-with-ca
Returns 200 OK · application/json
-
statusbooleanfalsewhen Frontrun reports a failure. -
messagestringFrontrun's message. -
dataanyReport payload; see above.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | handle is not a valid X handle. Send @name, name or an x.com profile link. |
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
| 404 | not_found | report is not info, smart-followers or tweets-with-ca. Use info, smart-followers or tweets-with-ca. |
| 422 | upstream_failure | The server has no Frontrun key, or the call to Frontrun failed in transit. Set FRONTRUN_API_KEY on the server, or retry later. |
| 429 | — | Frontrun rate limit (60 requests per minute). Relayed with Frontrun's own body, without a Proxima code. Wait a minute before the next Frontrun call. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.tracker.frontrunProfile(handle, endpoint) src/lib/proxima/endpoints/tracker.ts
Look up previous owners of a handle
/tracker/frontrun/old-username/{handle} Returns the X accounts that used this handle before renaming away from it.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Path parameters
-
handlestring RequiredX handle, without@.Exampleexamplecaller
Returns 200 OK · application/json
-
statusbooleanfalsewhen Frontrun reports a failure. -
messagestringFrontrun's message. -
dataobjectLookup result.Child attributes 2
-
foundbooleanWhether earlier owners were found. -
profilesarray<object>Earlier accounts. The app readstwitterUsername(orusername,twitter),nameandprofilePhoto.
-
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | handle is not a valid X handle. Send @name, name or an x.com profile link. |
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
| 422 | upstream_failure | The server has no Frontrun key, or the call to Frontrun failed in transit. Set FRONTRUN_API_KEY on the server, or retry later. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.tracker.frontrunOldUsername(handle) src/lib/proxima/endpoints/tracker.ts
Retrieve Frontrun credits
/tracker/frontrun/credits Returns the Frontrun credit balance of the tracker's API key.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Parameters
No parameters.
Returns 200 OK · application/json
-
statusbooleanfalsewhen Frontrun reports a failure. -
dataobjectCredit balance.Child attributes 2
-
currentPointsnumberCredits left. -
totalCreditsstringTotal credits, as a numeric string.
-
Errors
| Status | Code | When and what to do |
|---|---|---|
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
| 422 | upstream_failure | The server has no Frontrun key, or the call to Frontrun failed in transit. Set FRONTRUN_API_KEY on the server, or retry later. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.tracker.frontrunCredits() src/lib/proxima/endpoints/tracker.ts
Suggest token names for a tweet
/tracker/suggest Returns name and ticker picks for a tweet, to prefill a token deploy.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Picks are made once per tweet
idand saved; a repeat returns the saved picks.
The web app asks for three picks per tweet, once the tweet card scrolls into view, and caches them for the session. The SDK returns the suggestions array.
Body parameters application/json
-
idstring OptionalTweet ID. -
textstring OptionalTweet text. -
handlestring OptionalAuthor handle. -
followersinteger | null OptionalAuthor follower count. -
mediaarray<string> OptionalPhoto URLs. -
postersarray<string> OptionalVideo poster URLs. -
avatarstring | null OptionalAuthor avatar URL. -
quoted_handlestring | null OptionalHandle of the quoted tweet's author. -
quoted_textstring | null OptionalText of the quoted tweet. -
quoted_mediaarray<string> OptionalPhoto URLs of the quoted tweet. -
reply_tostring | null OptionalHandle the tweet replies to. -
cashtagsarray<string> OptionalCashtags in the text, without$.
Returns 200 OK · application/json
Returns a list of Suggestion objects.
-
suggestionsarray<object>Suggestion objects.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
| 422 | unprocessable | The examples the suggestions rely on cannot be loaded. Check the trench examples on the server (TRENCH_AI_DIR). |
| 422 | upstream_failure | The server has no Gemini key. Set GEMINI_API_KEY on the server. |
| 422 | upstream_failure | Gemini returned no usable suggestion for this tweet. Retry, or name the token by hand. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.tracker.suggest(tweet) src/lib/proxima/endpoints/tracker.ts
Analyze a tweet image
/tracker/vision Detects the subjects and legible texts in an image, with their positions.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Results are cached per image for an hour.
Send either url (an X media URL) or image (a data:image/...;base64, URL for an image only the browser holds, such as a captured video frame). The SDK picks the field from the source string. Boxes are in percent of the image, from 0 to 100. The app draws them over tweet images when detect vision is on.
Body parameters application/json
-
urlstring OptionalX media URL. Send this orimage. -
imagestring OptionalImage as adata:URL. Send this orurl.
Returns 200 OK · application/json
-
subjectsarray<object>Detected subjects.Child attributes 2
-
labelstringWhat the subject is. -
boxobject{ x, y, width, height }in percent of the image.
-
-
textsarray<object>Legible texts.Child attributes 4
-
textstringText as read. -
namestringToken name derived from the text. -
symbolstringTicker derived from the text. -
boxobject{ x, y, width, height }in percent of the image.
-
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | The body has both url and image, or neither. Send exactly one of url and image. |
| 400 | bad_request | url is not a valid URL. Send the full https URL of the image. |
| 400 | bad_request | url is not an https image on pbs.twimg.com, abs.twimg.com or video.twimg.com. Send an X media URL, or the image itself in image. |
| 400 | bad_request | image is not a base64 data: URL. Send image as data:image/<type>;base64,<data>. |
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
| 422 | unprocessable | The URL or the data does not hold an image. Send an image. |
| 422 | unprocessable | The image is larger than 8 MB. Send an image under 8 MB. |
| 422 | upstream_failure | The X media host answered an error status for url. Check that the image still exists on X. |
| 422 | upstream_failure | The server has no Gemini key. Set GEMINI_API_KEY on the server. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client proxima.tracker.vision(source) src/lib/proxima/endpoints/tracker.ts
Search web images
/tracker/images Searches Google Images through Serper, to pick a deploy image.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Returns Serper's payload as relayed by the backend. The app reads imageUrl, title, thumbnailUrl, imageWidth, imageHeight and source (or domain) from each image, and caches results per query for the session.
Query parameters
-
qstring RequiredSearch query.Examplesea otter meme
Returns 200 OK · application/json
-
imagesarray<object>Image results.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | q is empty or longer than 120 characters. Send a query of 1 to 120 characters. |
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
| 422 | upstream_failure | The server has no Serper key. Set SERPER_API_KEY on the server. |
| 422 | upstream_failure | Serper answered an error status. Retry in a few minutes. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.tracker.images(query) src/lib/proxima/endpoints/tracker.ts
Retrieve a tweet
/tracker/fx/{tweet_id} Returns a public tweet's details from FxTwitter, used to walk reply threads and quote chains.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
The backend relays FxTwitter's status payload. The app reads id, text, url, author (screen_name, name, avatar_url, followers), media.all, created_timestamp (Unix seconds), replying_to, replying_to_status and quote. Requests run at most 4 at a time and results are cached for the session.
Path parameters
-
tweet_idstring RequiredTweet ID.Example1852200000000000001
Returns 200 OK · application/json
-
tweetobjectFxTwitter tweet object.
Errors
| Status | Code | When and what to do |
|---|---|---|
| 400 | bad_request | tweet_id is not 1 to 25 digits. Pass the numeric ID from the tweet URL. |
| 403 | forbidden | The caller is not an admin. Call it with an admin account's session. |
| 404 | — | The tweet was deleted or does not exist. Relayed from FxTwitter with its own body, without a Proxima code; the backend caches the miss for 10 minutes and the app caches it too. |
| 422 | upstream_failure | FxTwitter could not be reached. Retry in a few minutes. |
Also the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client proxima.tracker.fxTweet(id) src/lib/proxima/endpoints/tracker.ts