Get Inputs Progress Traces - Archetype AI Documentation

curl "https://api.u1.archetypeai.app/v0.5/batch/jobs/job_2abc3def4ghi5jkl6mno7pqr/inputs/progress/traces?buckets=50" \
  -H "Authorization: Bearer $ATAI_API_KEY"

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']}")

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)}`);
});

{
  "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 } }
    }
  ]
}

(empty body — cached representation matches the request's If-None-Match)

{
  "code": "NOT_FOUND",
  "message": "Job not found",
  "error_uid": "err_abc123"
}

{
  "detail": "Invalid access with key: api_key_not_found"
}

GET

batch

jobs

{id}

inputs

progress

traces

curl "https://api.u1.archetypeai.app/v0.5/batch/jobs/job_2abc3def4ghi5jkl6mno7pqr/inputs/progress/traces?buckets=50" \
  -H "Authorization: Bearer $ATAI_API_KEY"

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']}")

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)}`);
});

{
  "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 } }
    }
  ]
}

(empty body — cached representation matches the request's If-None-Match)

{
  "code": "NOT_FOUND",
  "message": "Job not found",
  "error_uid": "err_abc123"
}

{
  "detail": "Invalid access with key: api_key_not_found"
}

Requires version 1.1.0 or later of the Archetype platform.

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

string

required

The unique job identifier

integer

Number of bucket points to return. Clamped to [10, 1000]; defaults to 100.

Response

string

The job identifier

number

Width of each bucket, in seconds

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.

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 — 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.

curl "https://api.u1.archetypeai.app/v0.5/batch/jobs/job_2abc3def4ghi5jkl6mno7pqr/inputs/progress/traces?buckets=50" \
  -H "Authorization: Bearer $ATAI_API_KEY"

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']}")

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)}`);
});

{
  "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 } }
    }
  ]
}

(empty body — cached representation matches the request's If-None-Match)

{
  "code": "NOT_FOUND",
  "message": "Job not found",
  "error_uid": "err_abc123"
}

{
  "detail": "Invalid access with key: api_key_not_found"
}

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.

⌘I

​Overview

​Request

​Response

Overview

Request

Response