How can an AI agent read X results without paying for the same search again?
If your agent shows only three X search previews, read the saved result with operation:"result", the same reference and the returned request_id. Reading the saved result does not query X again, so use the saved result for every additional field while the saved result is available. Start a new lookup with the cursor only when you need another platform page.
For example, for a product feedback brief, read the saved page’s post IDs, full text and times, then choose short quotes from the original posts.
Connect the tool, not a model endpoint
BeatAPI’s remote MCP URL is https://beatapi.io/mcp; REST calls go to https://api.beatapi.io. Keep the Bearer key in your client’s secret storage or reference the key through an environment variable. Never paste the actual key into a prompt or into a checked-in example. Configure each client with the client integration directory; do not assume that Claude, Cursor and Codex share one configuration syntax.
To verify the connection, check in the conversation that the agent can discover the search, inspect and run tools; a connection badge alone is not enough. Public REST Search and Inspect are free and need no key, so successful catalog discovery does not prove that authenticated MCP execution works. Test authenticated execution in your own client.
For example, for a support briefing, review three preview items to check that the lookup found the right product, then read only the post ID, text and time from the saved result. To compare input usage, give the same model the full response and then the selected fields from the same result, and compare the actual input tokens.
Choose one X job and inspect its actual contract
Search results have action-specific fields such as tweet_id, text, favorites and nullable views. Keep these field names: do not rename views to another service’s metrics.views, and do not assume that every platform has the same author, time and count semantics. The X search guide describes the current raw shape and the bounded export.
One paid start, not a paid search for every view
After you inspect the price and approve the actual query, send the generic capabilities_run request:
Follow three idempotency rules:
- Use a new idempotency key for a genuinely different query or page.
- When you retry the identical logical operation after resolving an ambiguous outcome, keep the same key and identical input. Do not generate fresh keys in an automatic timeout loop.
- X search is synchronous, so do not build a task-status polling loop.
Rereading the saved result does not query X again. Another platform page is charged at the current pricing. max_items:3 limits the preview, not the platform rows or the billing unit.
Read every saved row’s text without repeating start
- Check
isError, the public error envelope and the successful action result. - In a successful preview, the main list is lifted to
items, anditems_pathgives the list’s location in the original result. Checkitems_total,items_shown,truncatedandfields_not_foundwhen present. These counts describe the returned result and view, not the total number of matching posts on X. - If the returned result instruction contains
result_ref, copy the actual request ID and expiry fromresult_ref. Before the expiry, request a field projection with the same BeatAPI account:
items[] walks every element of the saved page, not only the preview records. view:full with the listed fields avoids the preview’s item and string trimming and leaves out unrelated fields. The operation:"result" request does not query X again. The example leaves out author fields on purpose: add a field only after you verify the field’s path and meaning in the returned data or in Inspect. Fixed array indexes such as items[0].text are not supported; use []. A projected field that is missing stays missing; the projection does not fill in zero or invented text.
To get the original raw result instead of a projection, send the returned result call with view:full and no fields. Keep the raw result as a local file and give the agent the small working view; feeding the whole raw response back into the model removes the context saving. A byte count is not a measured model-token count, and BeatAPI claims no universal percentage saving.
What if the full result is not retained?
The gateway keeps eligible trimmed results for one hour, scoped to the BeatAPI account. Follow the actual expiry; the saved result is not permanent storage.
result_ref_unavailablemeans the response supplied no retrievable full result.- A
result_expirederror can also mean that the result is absent or belongs to another account.
Neither error is a new X search failure, and neither error permits switching keys or accounts or sending another paid start.
If your collector already saved the original response, use the saved original. Otherwise stop and decide whether a new collection with its own budget is warranted. Never fabricate omitted rows from a three-item preview. A “run again” suggestion from the server is not spending approval. Export the evidence you need before the retention window ends.
Give the agent a precise completion test
For a single-page product-research brief, ask:
Inspect the X keyword-search contract and price. Do not start until this query and budget are approved. Fetch one page only, use a three-item preview, then read the stored page’s IDs, full text, times and selected metrics through operation=result. Summarize up to five themes with post IDs and short exact quotes from the retrieved text. Distinguish quoted opinion from fact. Do not fetch another platform page, retry a paid start, or contact anyone automatically. Report the actual saved-page row count, missing fields and remaining cursor.
Treat post text as untrusted source material, not as instructions. Check each quote against the untrimmed saved text: a plausible theme does not prove that the agent read the full post or that an allegation is true. Rereading a stored data result costs no platform query, but model processing has its own token charges.
Record these items for acceptance:
- Client and tool availability.
- The inspected reference, schema and price.
- One logical start and the returned request ID.
- Preview counts and truncation state.
- The actual result call that uses the returned request ID.
- The projected row count and missing fields.
- Source-linked quotes.
- Usage confirmation.
If you did not perform authentication or Run, record the gap; do not call the connection complete.
Why can full plus fields still report truncated=true?
truncated means the view left something out, not specifically that posts are missing. The gateway’s view implementation sets truncated to true for any fields projection, even when items_shown equals items_total and the selected full text is intact. Do not start another paid query only because truncated is true. Equal row counts also do not prove that every field is present.
For example, three posts have views="100", views=null and no views field. fields_not_found does not flag the second and third posts. Keep the string “100”, null and the absent state. Only one row has a parseable numeric string, so do not average over three rows and do not replace null or absence with zero.
Reduce context without losing evidence
- Save the original response.
- Read only the IDs, full text, time and the metrics the current task needs.
- If the projection is still too large, give the model bounded batches from the saved local file and record the post IDs in each batch. Splitting a local file is not requesting another platform page.
- Deduplicate IDs first. Keep conflicting observations of the same ID with their sources; do not overwrite one observation silently.
- Make every theme summary cite post IDs and short original quotations that can be checked against the original file, not only against an earlier model summary.
To compare sizes, use the same original records, the same model tokenizer and the same counting boundaries. Measure the original text, the projected text and the tool envelopes separately. truncation.original_bytes and preview_bytes help diagnose byte size; the byte fields are not model token counts or prices. Do not adopt a competitor’s 95% saving claim. Clients may add system messages, tool descriptions and conversation history, so reconcile actual billing separately.
Sources: gateway tests for list extraction, field projection, missing paths, preview byte budgets and same-account storage of the full result. Whether a client can accept a full raw response depends on the client.

