> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Inputs Progress Traces

> Bucketed cumulative file and per-kind item counters across the job lifetime

<Callout icon="clock" color="#3064E3" iconType="solid">
  Requires [version 1.1.0](/release-notes/1.1.x#v1-1-0) or later of the Archetype platform.
</Callout>

## Overview

Returns a fixed-resolution time series of cumulative file completions/failures (from `job_inputs`) and per-kind cumulative item counters (from `job_progress.metrics`) over the job's lifetime. Suitable for backing a job-progress chart.

`t` is the **end** of each bucket; the last point sits at the job's terminal timestamp (or `now()` for live jobs). The response supports `If-None-Match` — when the cached representation is still current, the endpoint returns `304 Not Modified`, letting polling clients short-circuit chart redraws.

## Request

<ParamField path="id" type="string" required>
  The unique job identifier
</ParamField>

<ParamField query="buckets" type="integer">
  Number of bucket points to return. Clamped to `[10, 1000]`; defaults to `100`.
</ParamField>

## Response

<ResponseField name="job_id" type="string">
  The job identifier
</ResponseField>

<ResponseField name="bucket_seconds" type="number">
  Width of each bucket, in seconds
</ResponseField>

<ResponseField name="latest_event_at" type="string">
  Timestamp of the most recent underlying event — `MAX` over `job_progress.created_at` and `job_inputs.completed_at`. `null` when the job has neither finished any inputs nor emitted any progress. Lets polling clients short-circuit redraws when nothing has changed since the previous poll.
</ResponseField>

<ResponseField name="points" type="array">
  Trace points, each containing:

  * `t` — RFC 3339 timestamp at the bucket end
  * `step` — Total finished inputs (`completed + failed`) at the bucket end. Matches the `step` from [List Inputs With Progress](/api-reference/batch/io/list-inputs-progress) — a 1-indexed completion rank across the job
  * `files` — Cumulative file-level counts at the bucket end: `{ "completed": int, "failed": int }`
  * `items` — Per-kind cumulative item counters from `job_progress.metrics`. Keys are the distinct `job_progress.kind` values observed for the job; values are `{ "success": int, "failed": int }`. Empty when no progress has been emitted yet.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"system"}
  curl "https://api.u1.archetypeai.app/v0.5/batch/jobs/job_2abc3def4ghi5jkl6mno7pqr/inputs/progress/traces?buckets=50" \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

  ```python Python theme={"system"}
  import requests
  import os

  api_key = os.environ.get("ATAI_API_KEY")
  job_id = "job_2abc3def4ghi5jkl6mno7pqr"

  response = requests.get(
      f"https://api.u1.archetypeai.app/v0.5/batch/jobs/{job_id}/inputs/progress/traces",
      headers={"Authorization": f"Bearer {api_key}"},
      params={"buckets": 50},
  )

  data = response.json()
  print(f"  bucket_seconds={data['bucket_seconds']} latest={data['latest_event_at']}")
  for p in data["points"][-3:]:
      print(f"    {p['t']} step={p['step']} files={p['files']} items={p['items']}")
  ```

  ```javascript JavaScript theme={"system"}
  const jobId = 'job_2abc3def4ghi5jkl6mno7pqr';
  const params = new URLSearchParams({ buckets: '50' });

  const response = await fetch(`https://api.u1.archetypeai.app/v0.5/batch/jobs/${jobId}/inputs/progress/traces?${params}`, {
    headers: { 'Authorization': `Bearer ${process.env.ATAI_API_KEY}` }
  });

  const data = await response.json();
  console.log(`bucket_seconds=${data.bucket_seconds} latest=${data.latest_event_at}`);
  data.points.slice(-3).forEach(p => {
    console.log(`  ${p.t} step=${p.step} files=${JSON.stringify(p.files)} items=${JSON.stringify(p.items)}`);
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={"system"}
  {
    "job_id": "job_2abc3def4ghi5jkl6mno7pqr",
    "bucket_seconds": 30.0,
    "latest_event_at": "2026-04-14T10:15:00Z",
    "points": [
      {
        "t": "2026-04-14T10:02:30Z",
        "step": 0,
        "files": { "completed": 0, "failed": 0 },
        "items": {}
      },
      {
        "t": "2026-04-14T10:03:00Z",
        "step": 0,
        "files": { "completed": 0, "failed": 0 },
        "items": { "inference": { "success": 1, "failed": 0 } }
      },
      {
        "t": "2026-04-14T10:15:00Z",
        "step": 9,
        "files": { "completed": 8, "failed": 1 },
        "items": { "inference": { "success": 478, "failed": 12 } }
      }
    ]
  }
  ```

  ```json 304 - Not Modified theme={"system"}
  (empty body — cached representation matches the request's If-None-Match)
  ```

  ```json 404 - Not Found theme={"system"}
  {
    "code": "NOT_FOUND",
    "message": "Job not found",
    "error_uid": "err_abc123"
  }
  ```

  ```json 401 - Unauthorized theme={"system"}
  {
    "detail": "Invalid access with key: api_key_not_found"
  }
  ```
</ResponseExample>

<Tip>
  Save `latest_event_at` between polls and send it via the `If-None-Match` header. The server returns `304 Not Modified` when nothing has changed, letting you skip the chart redraw.
</Tip>