Monitor & Debug — Developers

After you submit a job, you’ll want to track its progress, inspect results, and debug any failures. This guide shows you how.

Check Job Status

Get the current state of any job:

curl https://api.swarmient.com/v1/jobs/job_abc123 \
  -H "Authorization: Bearer $SWARMIENT_API_KEY"

Response includes everything:

{
  "job_id": "job_abc123",
  "name": "generate-api",
  "status": "RUNNING",
  "created_at": "2026-07-08T12:00:00Z",
  "updated_at": "2026-07-08T12:00:05Z",
  "tasks": [
    {
      "id": "task-1",
      "status": "COMPLETED",
      "result": "...",
      "execution_time_ms": 2340,
      "cost": 0.05
    },
    {
      "id": "task-2",
      "status": "RUNNING",
      "miner_id": "miner_xyz789",
      "started_at": "2026-07-08T12:00:05Z"
    }
  ],
  "total_cost": 0.05,
  "estimated_remaining_cost": 0.10
}

Status values:

PENDING — Waiting for a miner to accept
RUNNING — A miner is working on it
COMPLETED — Task succeeded
FAILED — Task failed (see error field)
TIMEOUT — Task exceeded the timeout limit

Streaming Results

For real-time updates, use Server-Sent Events (SSE):

curl https://api.swarmient.com/v1/jobs/job_abc123/stream \
  -H "Authorization: Bearer $SWARMIENT_API_KEY"

You’ll get events as the job progresses:

event: task_started
data: {"task_id": "task-1", "miner_id": "miner_xyz789"}

event: task_completed
data: {"task_id": "task-1", "result": "...", "execution_time_ms": 2340, "cost": 0.05}

event: task_started
data: {"task_id": "task-2", "miner_id": "miner_abc123"}

event: job_completed
data: {"total_cost": 0.15, "status": "COMPLETED"}

Great for dashboards, logging, or integrating into your CI/CD pipeline.

Inspect Results

View a single task’s result:

curl https://api.swarmient.com/v1/jobs/job_abc123/tasks/task-1 \
  -H "Authorization: Bearer $SWARMIENT_API_KEY"

Response:

{
  "id": "task-1",
  "status": "COMPLETED",
  "result": "def quicksort(arr):\n    if len(arr) <= 1:\n        return arr\n    ...",
  "result_size_bytes": 1256,
  "miner_id": "miner_xyz789",
  "execution_time_ms": 2340,
  "cost": 0.05,
  "proof": {
    "signature": "...",
    "miner_public_key": "...",
    "algorithm": "Ed25519"
  }
}

If the result is large (> 1MB), it’ll be truncated. Fetch the full result:

curl https://api.swarmient.com/v1/jobs/job_abc123/tasks/task-1/result \
  -H "Authorization: Bearer $SWARMIENT_API_KEY" \
  > result.txt

Verify Proofs

Every result comes with a proof—a cryptographic signature proving the miner executed the task correctly.

You can verify the proof using Swarmient’s verification library:

Python:

from swarmient import verify_proof

result = "... miner's result ..."
proof = {
    "signature": "...",
    "miner_public_key": "...",
    "algorithm": "Ed25519"
}

is_valid = verify_proof(result, proof)
print(f"Result is valid: {is_valid}")

JavaScript:

import { verifyProof } from 'swarmient-js';

const result = "... miner's result ...";
const proof = {
  signature: "...",
  minerPublicKey: "...",
  algorithm: "Ed25519"
};

const isValid = await verifyProof(result, proof);
console.log(`Result is valid: ${isValid}`);

Why verify? Because you can audit miners independently. You don’t have to trust Swarmient or any miner—just the math.

Debug Failures

When a task fails, check the error field:

curl https://api.swarmient.com/v1/jobs/job_abc123/tasks/task-1 \
  -H "Authorization: Bearer $SWARMIENT_API_KEY" | jq '.error'

Response:

{
  "code": "TIMEOUT",
  "message": "Task exceeded 30000ms timeout",
  "details": {
    "timeout_ms": 30000,
    "execution_time_ms": 32145
  }
}

Common error codes and solutions:

Error Code	Meaning	Solution
`TIMEOUT`	Task took longer than timeout	Increase `timeout_ms` in your job
`MINER_DISCONNECTED`	Miner crashed or went offline	Enable retries with `max_retries: 2`
`INSUFFICIENT_RESOURCES`	No miners had GPU/memory you requested	Reduce resource requirements or wait for more miners
`SANDBOX_ERROR`	Something broke in the miner’s sandbox	Check your prompt for instructions that might break the sandbox
`INVALID_PROMPT`	Your prompt was malformed	Make sure prompt is a non-empty string
`NETWORK_ERROR`	Network issue between you and miner	Retry with `max_retries` enabled

Task Times Out

Symptom: "error": {"code": "TIMEOUT"}

Diagnosis:

Did you set the timeout too low? (Try 60 seconds for medium tasks)
Is the prompt clear enough? (Vague prompts take longer)
Did you request resources that are rare? (Waiting for a GPU miner takes time)

Fix:

{
  "id": "slow-task",
  "prompt": "...",
  "timeout_ms": 120000,
  "max_retries": 2
}

Miner Disconnects

Symptom: "error": {"code": "MINER_DISCONNECTED"}

Diagnosis:

Miner crashed or went offline mid-task
Network was interrupted
Miner ran out of disk space

Fix:

{
  "id": "risky-task",
  "prompt": "...",
  "timeout_ms": 60000,
  "max_retries": 3
}

Swarmient will retry on a different miner.

Insufficient Resources

Symptom: "error": {"code": "INSUFFICIENT_RESOURCES"}

Diagnosis:

You requested GPU but no GPU miners are available
You requested 64GB RAM but max available is 32GB
Network is overloaded, all miners busy

Fix: Either relax requirements or wait and retry:

{
  "id": "picky-task",
  "prompt": "...",
  "resources": {
    "gpu": "optional",
    "memory_gb": 16
  },
  "max_retries": 2
}

Sandbox Errors

Symptom: "error": {"code": "SANDBOX_ERROR", "message": "... sandboxed execution failed ..."}

Diagnosis:

Your prompt asks the miner to do something outside a sandbox (access files, network)
Prompt asks for something that requires system packages

Fix:

Don’t ask miners to read/write system files
Don’t ask for network access
Don’t ask miners to install packages (they can use what’s pre-installed)
Keep prompts focused on code generation, data processing, math

List All Jobs

See your job history:

curl "https://api.swarmient.com/v1/jobs?limit=50&offset=0" \
  -H "Authorization: Bearer $SWARMIENT_API_KEY"

Response:

{
  "jobs": [
    {
      "job_id": "job_abc123",
      "name": "generate-api",
      "status": "COMPLETED",
      "created_at": "2026-07-08T12:00:00Z",
      "total_cost": 0.15
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

Query parameters:

limit — How many jobs to return (1–1000, default 50)
offset — Skip this many jobs (for pagination)
status — Filter by status (PENDING, RUNNING, COMPLETED, FAILED)
tag — Filter by tag (if you tagged your jobs)
created_after — ISO 8601 timestamp (e.g., 2026-07-01T00:00:00Z)

Example: Find all failed jobs from today

curl "https://api.swarmient.com/v1/jobs?status=FAILED&created_after=2026-07-08T00:00:00Z" \
  -H "Authorization: Bearer $SWARMIENT_API_KEY"

Dashboard

Your dashboard is the easiest way to monitor jobs:

Job list — All your jobs, filterable by status, tag, cost
Job detail — Click any job to see full results, costs, execution timeline
Real-time updates — Stream jobs to see progress in real-time
Cost tracking — See total spend this month, remaining credits
Miner info — View which miners executed your tasks, their hardware, ratings

Optimize Costs

Parallelize Where You Can

Instead of sequential tasks:

{
  "tasks": [
    { "id": "a", "prompt": "..." },
    { "id": "b", "prompt": "...", "depends_on": ["a"] },
    { "id": "c", "prompt": "...", "depends_on": ["b"] }
  ]
}

Use parallelization:

{
  "tasks": [
    { "id": "a", "prompt": "..." },
    { "id": "b", "prompt": "...", "depends_on": ["a"] },
    { "id": "c", "prompt": "..." },
    { "id": "d", "prompt": "..." }
  ]
}

Tasks c and d run while task b is executing.

Reduce Timeouts

Don’t set timeouts to 5 minutes if a task only needs 30 seconds:

{
  "id": "task-1",
  "prompt": "Write a hello world function",
  "timeout_ms": 30000
}

Lower timeouts = faster feedback and lower costs (if tasks fail, you stop paying sooner).

Batch Similar Tasks

Instead of 10 separate job submissions:

# Expensive: 10 API calls
curl -X POST .../submit -d '{"tasks": [...]}'
curl -X POST .../submit -d '{"tasks": [...]}'
curl -X POST .../submit -d '{"tasks": [...]}'
# ... 7 more calls

Combine into one job:

# Efficient: 1 API call
curl -X POST .../submit -d '{"tasks": [... all 10 tasks ...]}'

Swarmient handles parallelization automatically.

Next Steps

Pricing & Economics — Understand cost calculation
Examples — Real-world patterns and use cases
FAQ — Common troubleshooting questions