Job Management

​

Key Concepts

• Scheduled - Job is queued, waiting for worker assignment
• Running - Job is actively syncing blockchain data
• StopRequested - Stop signal sent, worker finishing current work
• Stopping - Worker is shutting down the job
• Completed - Job finished successfully (terminal state)
• Stopped - Job was stopped by operator (terminal state)
• Failed - Job encountered an error (terminal state)

​

Core Operations

​

List Jobs

# List first 50 jobs (default)
ampctl job list
ampctl job ls  # alias

# List first 100 jobs
ampctl job list --limit 100

# Paginate - get next 50 jobs after ID 1234
ampctl job list --after 1234

# Filter by status (default: "active" - non-terminal jobs)
ampctl job list --status all
ampctl job list --status scheduled,running
ampctl job list -s completed

# Short aliases
ampctl job list -l 20 -a 500

# JSON output
ampctl job list --json

{
  "jobs": [
    {
      "id": 12345,
      "status": "RUNNING",
      "dataset": {
        "namespace": "ethereum",
        "name": "mainnet",
        "version": "1.0.0"
      },
      "manifest_hash": "abc123...",
      "worker_id": "worker-01",
      "created_at": "2026-03-04T10:00:00Z",
      "updated_at": "2026-03-04T11:30:00Z"
    }
  ],
  "next_cursor": 12346
}

• active (default) - Shows non-terminal jobs (Scheduled, Running, StopRequested, Stopping)
• all - Shows all jobs including terminal states
• Comma-separated values - scheduled,running,completed,stopped,error

​

Inspect a Job

# Inspect by job ID
ampctl job inspect 12345
ampctl job get 12345  # alias

# Extract specific fields
ampctl job inspect 12345 | jq '.status'
ampctl job inspect 12345 --json

{
  "id": 12345,
  "status": "RUNNING",
  "dataset": {
    "namespace": "ethereum",
    "name": "mainnet",
    "version": "1.0.0"
  },
  "manifest_hash": "abc123...",
  "worker_id": "worker-01",
  "end_block": null,
  "parallelism": 1,
  "created_at": "2026-03-04T10:00:00Z",
  "updated_at": "2026-03-04T11:30:00Z"
}

​

Monitor Job Progress

# Get job progress
ampctl job progress 123

# JSON output for scripting
ampctl job progress 123 --json

{
  "job_id": 123,
  "job_status": "RUNNING",
  "tables": {
    "blocks": {
      "current_block": 21500000,
      "start_block": 0,
      "files_count": 1247,
      "total_size_bytes": 137970286592
    },
    "transactions": {
      "current_block": 21499850,
      "start_block": 0,
      "files_count": 3891,
      "total_size_bytes": 549957091328
    }
  }
}

• current_block - Highest block in contiguous synced range
• start_block - Lowest block in synced range
• files_count - Number of Parquet files written
• total_size_bytes - Total data size in bytes

​

Stop a Job

# Stop a job
ampctl job stop 12345

# Verify job stopped
ampctl job inspect 12345

• Worker finishes current operations before stopping
• Job transitions: Running → StopRequested → Stopping → Stopped
• Idempotent: stopping an already stopped job returns success
• Verify completion with ampctl job inspect

​

Remove a Job

# Remove by job ID
ampctl job rm 123
ampctl job remove 456  # alias

• Only jobs in terminal states (Completed, Stopped, Failed) can be removed
• Running jobs must be stopped first
• Returns 409 Conflict if job is not in terminal state
• Idempotent: deleting non-existent job returns success (204)

​

Prune Terminal Jobs

# Prune all terminal jobs (completed, stopped, error)
ampctl job prune

# Prune only completed jobs
ampctl job prune --status completed

# Prune only failed jobs
ampctl job prune --status error

# Prune only stopped jobs
ampctl job prune --status stopped

• Periodic cleanup of completed jobs
• Administrative maintenance
• Freeing up database storage

​

Scripting Examples

​

Find Running Jobs for Dataset

# Find all running jobs for ethereum/mainnet
ampctl job list --json | jq '.jobs[] | 
  select(.status == "RUNNING" and .dataset.name == "mainnet")'

​

Monitor Progress Continuously

# Watch job progress in real-time
watch -n 5 'ampctl job progress 123'

​

Alert on Failed Jobs

#!/bin/bash
# Check for failed jobs
failed=$(ampctl job list --status error --json | jq '.jobs | length')

if [ $failed -gt 0 ]; then
  echo "ALERT: $failed failed jobs detected"
  ampctl job list --status error
fi

​

Clean Up Old Completed Jobs

# Remove all completed jobs older than 7 days
ampctl job prune --status completed

​

API Reference

• limit - Maximum jobs to return (default: 50, max: 1000)
• last_job_id - Cursor for pagination
• status - Status filter (active, all, or comma-separated values)

• status - Required filter (terminal, completed, stopped, error)

​

Next Steps