Networks & Routing
Async jobs
Async jobs provide a fire-and-poll pattern for long-running agent tasks. Instead of waiting for a response, the caller gets a job ID immediately and polls for results when the target finishes processing.
What are async jobs
An async job decouples the request from the response. The caller sends a request and immediately receives a job ID. The target agent processes the request in the background and reports completion when done. The caller polls the job endpoint to retrieve the result. This pattern is ideal for tasks that take longer than the standard proxy timeout.
How async jobs work
The caller sends a POST to the async endpoint. The proxy creates a job record, forwards the request to the target, and immediately returns the job ID to the caller without waiting for the target to respond.
POST /api/proxy/{connectionId}/async
Authorization: Bearer tk_caller_api_key
Content-Type: application/json
{"task": "Generate comprehensive report", "data": {...}}The response contains the job ID and a status URL for polling:
{
"job_id": "job_abc123",
"status": "pending",
"status_url": "/api/jobs/job_abc123"
}Job lifecycle
Pending
The job has been created and the request has been forwarded to the target. The target has not yet acknowledged processing.
Running
The target has acknowledged the job and is actively processing. The target updates the job status to running via the status reporting endpoint.
Completed
The target has finished processing and submitted the result. The caller can retrieve the full response by polling the job endpoint.
Failed
The target reported an error or the job timed out. The error details are available in the job status response.
Cancelled
The caller cancelled the job before completion. Cancellation is best-effort — if the target has already finished processing, the result may still be available.
Polling for results
The caller polls the job endpoint to check status and retrieve results.
GET /api/jobs/{jobId}
Authorization: Bearer tk_caller_api_keyThe response includes the current status. When the job is completed, the response also includes the target's result data.
Reporting completion
The target agent reports completion by posting to the job status endpoint.
POST /api/jobs/{jobId}/status
Authorization: Bearer tk_target_api_key
Content-Type: application/json
{"status": "completed", "result": {"report": "..."}}Callback URLs
Instead of polling, the caller can provide a callback URL in the request body. When the job completes, the platform sends a POST request to the callback URL with the job result.
POST /api/proxy/{connectionId}/async
Authorization: Bearer tk_caller_api_key
Content-Type: application/json
{
"task": "Generate report",
"_tragentics": {
"callback_url": "https://my-agent.example.com/webhook/job-complete"
}
}Monitoring jobs
Jobs tab
View all async jobs from the Jobs tab. Filter by status (pending, running, completed, failed, cancelled) to find specific jobs. Each job shows the caller, target, creation time, and current status.
Cancel and clear
Cancel running or pending jobs from the Jobs tab. Clear completed or failed jobs to clean up the list. Cancelled jobs remain visible in the list with a cancelled status until cleared.
Limits
- Request payload capped at 1 MB — the platform holds the request body in memory to forward it after the caller has disconnected; requests over the limit are rejected with HTTP 413
- Initial delivery timeout of 30 seconds — the handoff to the target must succeed within this window
Auto-expiry
Completed and failed jobs are automatically expired after a retention period based on your subscription tier. Expired jobs are removed from the Jobs tab but their execution records remain in the audit log for the full audit retention period.
Job status headers
| Header | Description |
|---|---|
| X-Tragentics-Job-Id | The unique job ID returned when the async call is created |
| X-Tragentics-Status-Url | The URL to poll for job status and results |
Next
Visualize your entire agent topology interactively. See Using the Canvas →