Async Operations

GET /v1/operations/:operationId — Check the status of an async operation.

Overview

Property	Value
Auth	Bearer token (OIDC, must match tenant)
Idempotent	N/A (read-only)

Operation States


queued → running → succeeded
                 → failed
                 → cancelled

State	Description
`queued`	Task enqueued, waiting for worker
`running`	Worker is actively processing
`succeeded`	Completed successfully, result available
`failed`	Processing failed, error details available
`cancelled`	Operation was cancelled

Response (200)


{
  "operation_id": "uuid",
  "request_id": "string",
  "tenant_id": "string",
  "endpoint": "proofread | essay-critique | onboarding-certify",
  "status": "queued | running | succeeded | failed | cancelled",
  "created_at": "ISO8601",
  "updated_at": "ISO8601",
  "completed_at": "ISO8601 | undefined",
  "provider": "gemini | undefined",
  "model": "string | undefined",
  "latency_ms": "number | undefined",
  "result": "object | undefined",
  "error": { "code": "string", "message": "string" }
}

How Async Routing Works

Request arrives at a core endpoint (proofread or essay-critique)
If text exceeds SYNC_TEXT_THRESHOLD (1200 chars) or Prefer: respond-async header is set, the API routes to the async path
An operation record is created with status queued
The task is enqueued to Cloud Tasks (production) or an in-memory queue (development)
A worker claims the operation and transitions it: queued → running → succeeded / failed
The client polls /v1/operations/:id until a terminal state

Sync Timeout Fallback

If a sync request exceeds the SYNC_TIMEOUT_MS threshold (default 8000ms), the system automatically:

Creates an operation record
Enqueues the task for async processing
Returns 202 with a poll_url

Polling Example


# Initial request returns 202
OPERATION_ID="op-uuid-from-response"
 
# Poll until terminal state
while true; do
  RESPONSE=$(curl -s "$GOTAMIL_API/v1/operations/$OPERATION_ID" \
    -H "Authorization: Bearer $TOKEN")
 
  STATUS=$(echo "$RESPONSE" | jq -r '.status')
  echo "Status: $STATUS"
 
  if [ "$STATUS" = "succeeded" ] || [ "$STATUS" = "failed" ]; then
    echo "$RESPONSE" | jq .
    break
  fi
 
  sleep 2
done