Jobs API

GET /api/v1/jobs/{id}

Retrieves the current status of an asynchronous job and returns the result when it is ready. Use this after submitting any async operation, such as Screen Analysis.

The public job envelope is intentionally minimal. It exposes only the fields clients need to continue the workflow; internal timing and queue metadata are omitted from v1.

Job creation stays domain-specific. For example, POST /api/v1/analysis/screen creates a screen-analysis job. Job retrieval is universal: every async job is retrieved through GET /api/v1/jobs/{id}.

Parameters

Name	In	Type	Description
id	path	string	Job id returned by an async submit endpoint

Running Response

{
  "id": "job_01HY3K4M7QR9VP2N8WYJF5GTB",
  "type": "screen_analysis",
  "status": "running",
  "createdAt": "2026-04-15T12:00:00Z",
  "updatedAt": "2026-04-15T12:00:05Z",
  "result": null,
  "error": null
}

Succeeded Response

{
  "id": "job_01HY3K4M7QR9VP2N8WYJF5GTB",
  "type": "screen_analysis",
  "status": "succeeded",
  "createdAt": "2026-04-15T12:00:00Z",
  "updatedAt": "2026-04-15T12:00:12Z",
  "result": {
    "type": "analysis.screen.result",
    "riskScore": 75,
    "findings": [
      {
        "priority": "p1",
        "title": "Missing provisional credit disclosure",
        "details": "The content states that provisional credit cannot be provided until the investigation is completed. Under Regulation E, financial institutions must provisionally credit the consumer's account within 10 business days.",
        "citations": [
          {
            "regulation": {
              "id": "01HXZ3K4M7QR9VP2N8WYJF5GTB",
              "category": "regulation",
              "title": "Electronic Fund Transfers",
              "authorities": ["cfpb"],
              "jurisdictions": ["us-federal"],
              "description": "Regulation E error-resolution requirements for financial institutions.",
              "updatedAt": "2026-04-09T00:00:00Z",
              "sourceUrl": "https://www.ecfr.gov/current/title-12/chapter-X/part-1005/section-1005.11"
            },
            "chunks": [
              {
                "text": "If the financial institution is unable to complete its investigation within 10 business days...",
                "startOffset": 12450,
                "endOffset": null
              }
            ]
          }
        ]
      }
    ]
  },
  "error": null
}

Failed Response

{
  "id": "job_01HY3K4M7QR9VP2N8WYJF5GTB",
  "type": "screen_analysis",
  "status": "failed",
  "createdAt": "2026-04-15T12:00:00Z",
  "updatedAt": "2026-04-15T12:00:30Z",
  "result": null,
  "error": {
    "code": "analysis_failed",
    "message": "The screening job could not be completed. Retry with the same content or contact support if the issue persists."
  }
}

Job Fields

Field	Type	Description
id	string	Stable job id
type	string	Job type discriminator. Clients should branch on this before reading result.
status	string	One of running, succeeded, or failed
createdAt	string	ISO 8601 UTC timestamp of when the job was submitted
updatedAt	string	ISO 8601 UTC timestamp of the last status transition
result	object or null	Present only when status is succeeded. Shape depends on type.
error	object or null	Present only when status is failed. Shape: { code, message }.

Job Types

The job envelope is universal, but result is typed by type. v1 defines the following job types; additional async APIs may add new types without changing the envelope.

type	Created by	Result shape
screen_analysis	POST /analysis/screen	{ type, riskScore, findings } — result type discriminator, risk score, and compliance findings with regulatory citations. See Screen Analysis Result.

Clients should branch on type before reading result-specific fields.

Polling Guidance

Poll GET /api/v1/jobs/{id} until status is succeeded or failed. Those two states are terminal. Back off between polls — start around 1 second and grow the interval as the job remains non-terminal.

The job result is returned inline from this endpoint. There is no separate result endpoint in v1.