Skip to main content
Job endpoints allow you to trigger, monitor, and manage data extraction jobs in Amp. Jobs are the runtime execution units that process blockchain data according to dataset configurations.

​
List Jobs

Retrieves a paginated list of jobs from the metadata database.

​
Query Parameters

​
limit
integer
Maximum number of jobs to return (default: 50, max: 1000)
​
last_job_id
string
ID of the last job from the previous page for cursor-based pagination
​
status
string
Status filter:
  • active (default): Non-terminal jobs only
  • all: All jobs
  • Comma-separated values: e.g., scheduled,running

​
Response

​
jobs
array
required
List of jobs
​
next_cursor
integer
Cursor for the next page (null if no more results)

​
Example Request

curl "http://localhost:1610/jobs?limit=10&status=active"

​
Example Response

{
  "jobs": [
    {
      "id": 12345,
      "created_at": "2025-01-15T14:30:00.123456Z",
      "updated_at": "2025-01-15T17:20:15.456789Z",
      "node_id": "worker-01h2xcejqtf2nbrexx3vqjhp41",
      "status": "Running",
      "descriptor": {
        "dataset": "eth/[email protected]",
        "start_block": 0,
        "end_block": null
      }
    }
  ],
  "next_cursor": 12346
}

​
Get Job Details

Retrieves detailed information for a specific job by its ID.

​
Path Parameters

​
id
string
required
The unique identifier of the job to retrieve

​
Response

​
id
integer
required
Unique job identifier
​
created_at
string
required
Job creation timestamp (ISO 8601 / RFC 3339)
​
updated_at
string
required
Job last update timestamp (ISO 8601 / RFC 3339)
​
node_id
string
required
Worker node ID this job is scheduled for
​
status
string
required
Current job status
​
descriptor
object
required
Job descriptor with job-specific parameters

​
Example Request

curl http://localhost:1610/jobs/12345

​
Response Codes

  • 200 OK - Job information retrieved successfully
  • 400 Bad Request - Invalid job ID format
  • 404 Not Found - Job not found
  • 500 Internal Server Error - Database error

​
Get Job Progress

Retrieves progress information for all tables written by a specific job, including current block numbers, file counts, and size statistics.

​
Path Parameters

​
id
string
required
The unique identifier of the job

​
Response

​
job_id
integer
required
Job ID
​
job_status
string
required
Current job status
​
tables
object
required
Progress for each table written by this job, keyed by table name

​
Example Request

curl http://localhost:1610/jobs/12345/progress

​
Example Response

{
  "job_id": 12345,
  "job_status": "Running",
  "tables": {
    "blocks": {
      "files_count": 150,
      "total_size_bytes": 5368709120,
      "start_block": 0,
      "current_block": 15000000
    },
    "transactions": {
      "files_count": 280,
      "total_size_bytes": 12884901888,
      "start_block": 0,
      "current_block": 15000000
    }
  }
}

​
Stop Job

Stops a running job gracefully. This is an idempotent operation - stopping an already stopped job returns success.

​
Path Parameters

​
id
integer
required
The unique identifier of the job to stop

​
Response Codes

  • 200 OK - Job stop request processed successfully
  • 400 Bad Request - Invalid job ID format
  • 404 Not Found - Job not found
  • 500 Internal Server Error - Database error

​
State Transitions

Valid stop transitions:
  • Scheduled → StopRequested (200 OK)
  • Running → StopRequested (200 OK)
Already terminal (idempotent - returns success):
  • Stopped → no change (200 OK)
  • Completed → no change (200 OK)
  • Failed → no change (200 OK)

​
Example Request

curl -X PUT http://localhost:1610/jobs/12345/stop

​
Delete Job

Deletes a job by its ID if it’s in a terminal state (Completed, Stopped, or Failed). This is a safe, idempotent operation.

​
Path Parameters

​
id
integer
required
The unique identifier of the job to delete

​
Response Codes

  • 204 No Content - Job deleted successfully or doesn’t exist
  • 400 Bad Request - Invalid job ID format
  • 409 Conflict - Job exists but is not in a terminal state
  • 500 Internal Server Error - Database error

​
Terminal States

Jobs can only be deleted when in these states:
  • Completed - Safe to delete
  • Stopped - Safe to delete
  • Failed - Safe to delete
Protected states (cannot be deleted):
  • Scheduled - Job is waiting to run
  • Running - Job is actively executing
  • StopRequested - Job is being stopped
  • Stopping - Job is in process of stopping

​
Example Request

curl -X DELETE http://localhost:1610/jobs/12345

​
Bulk Delete Jobs

Deletes multiple jobs based on status filter. Only jobs in terminal states are deleted.

​
Query Parameters

​
status
string
required
Status filter for jobs to delete:
  • terminal: All terminal state jobs
  • completed: All completed jobs
  • stopped: All stopped jobs
  • error: All failed jobs

​
Response Codes

  • 204 No Content - Operation completed successfully
  • 400 Bad Request - Invalid or missing status parameter
  • 500 Internal Server Error - Database error

​
Example Request

curl -X DELETE "http://localhost:1610/jobs?status=completed"
Non-terminal jobs are completely protected from deletion. The database ensures atomic bulk deletion.

Build docs developers (and LLMs) love

Get started for freeTalk to us