Preview: tested locally with Python 3.12, OpenAI Agents SDK 0.22.3 and Pydantic 2.13.5. Tests use a scripted model and simulated HTTP responses. Real-model, live-account and real-source acceptance remain pending.
Canonical submission and original-command recovery
Use POST /v1/quotes, then POST /v1/tasks with productId, the approved input, the quoted expectedPricingVersion, and the canonical Idempotency-Key. The host creates a key once for explicitly approved new work, using new_command_key() from the bundled REST engine, and persists it with the approved input before submission. Keys have the form v1.<13-digit Unix milliseconds>.<22–64 base64url characters>. Do not generate keys in model arguments or a workflow retry expression.
Creation requires allow_write=True, the persisted request_key, and explicit command_mode="new". The default command_mode="recover" performs an original-command GET and never obtains another quote or submits again. Repeated invocation in the same new-intent toolset also reads the original after its first submission attempt. Changed input is refused. After a restart or any lost response, use this host-only path; it needs no input, quote or model call:
import os
from truefetch_rest import recover_command, observed_task_id
original = recover_command(
os.environ["TRUEFETCH_API_KEY"], "tasks.create", os.environ["TRUEFETCH_COMMAND_KEY"]
)
if original["receipt"]["outcome"] == "accepted":
saved_task_id = observed_task_id(original)
# Persist the reference before reading the existing task/results.HTTP 200 is not acceptance. Inspect receipt.outcome: accepted supplies an authoritative task reference even when the current task projection is null; processing and unknown require another explicit original GET, respecting the returned retry interval. rejected and not_accepted_final establish nonacceptance and require deliberate new work if you still want a collection. receipt_expired remains unconfirmed: inspect Tasks or contact support. The helper never seals, replays a POST or creates a replacement key. The server accepts new keys for 24 hours, allows five minutes of future clock skew, and retains terminal receipts for at least seven days; it can still answer a retained original after the new-command window ends. A current Task state does not establish a particular command’s outcome.
Cancellation is a separate command: bind a different persisted canonical cancel_key for the newly created task, or pass cancel_task_ids=(saved_task_id,) and cancel_command_keys={saved_task_id: saved_cancel_key} for an explicitly approved saved target. POST /v1/tasks/{taskId}/cancel sends {} and that cancellation key. Unknown cancellation is recovered with recover_command(api_key, "tasks.cancel", saved_cancel_key), never the creation key. Acceptance of cancellation does not promise the task ended as cancelled. The budget, keys and cancellation mapping remain host-only arguments.
Download and configure
Save all five files in one directory:
Install the requirements in a Python virtual environment. Set TRUEFETCH_API_KEY in your host environment. Your model provider needs its own credentials; OpenAI credentials are separate from TrueFetch’s. Supply your selected SDK model explicitly.
One intent, one budget
Construct Toolset(api_key, max_credits=100) for usage, estimation, task reads and task listing. To enable creation and scoped cancellation, the host adds allow_write=True, command_mode="new" and a saved canonical request_key. Credentials, budget and request key are excluded from model arguments. Set account-wide API-key limits separately.
Creation checks a fresh estimate and pricing version against the fixed budget. It reserves credits and can incur collection charges; model charges are separate. Save the task ID immediately. After interruption, GET the original receipt using the saved canonical key. A changed input is a different intent, not a safe retry.
Run an agent and recover complete records
The downloadable runner uses native Agent, Runner and FunctionTool interfaces. It bounds model turns and tool calls, disables SDK tracing and returns observed task IDs. It defaults to read-only tools. Reading a task never enables cancellation; only IDs created in this toolset or explicitly allowed by the host can be cancelled.
Use await tools.recover(saved_task_id) outside the model loop for a complete export. Recovery checks every result page, task identity, status, count and ordering. It returns complete, partial, task and data; task metadata retains source outcomes and expiry. An individual tool page or model summary is not a complete export, and complete pagination does not imply exhaustive coverage.
Failure and data boundaries
Authentication, budget, pricing, expired results and inconsistent pages stop the operation. An agent failure retains observed task IDs. Timeouts cannot stop an already-running HTTP thread or remote task; a late acceptance may be absent from those IDs. Preserve the original key/input and inspect your workspace before starting another collection. Original-command recovery does not need a quote; use the saved key before deciding on new work. HTTP calls use a 30-second timeout; recovery’s deadline is checked between blocking calls.
The helper does not automatically retry collection or cancel tasks. Source descriptions are untrusted data. Tool arguments and returned pages are sent to your configured model, so control provider retention, access and logs. Disabled SDK tracing does not change provider policies or prove protection from prompt injection. Saved results remain available only through their retention window.
Detailed setup · Job Search API · All integrations · Official SDK documentation
The shared REST reader requires UTF-8 JSON and rejects nonfinite numbers, including numeric overflow. Interrupted or oversized HTTP error bodies keep a redacted HTTP-status diagnostic, and truncated successful transfers fail without returning data. It also rejects duplicate member names within an object, including names written with equivalent Unicode escapes; repeated names in separate records are allowed. Recovery also rejects nonfinite values from tool output instead of marking the export complete. Preserve the saved task ID and original request key after an error; these checks do not create or retry collection.
For each available result page, the reader checks the task again after receiving the page, including the final page. This adds one read-only task GET per page. Changed identity, status, availability or count, or a failed recheck, prevents a complete export. The check is a point-in-time observation; files can expire or become unavailable afterward.
Before collection, the creation tool checks that the estimate matches the requested input and that reserved billing units equal the record limit multiplied by the unit price. Amounts must be positive ASCII integers, and the reservation must fit the host credit budget. Invalid estimates stop before submission; server-side pricing and budget checks still apply.