Developer Guide

Submit Jobs — Developers

This guide covers everything you need to know to submit jobs to the Swarmient network.

Job Structure

Every job is a JSON object with a name and an array of tasks:

{
  "name": "my-first-job",
  "tasks": [
    {
      "id": "task-1",
      "prompt": "...",
      "timeout_ms": 30000
    }
  ]
}

Required fields:

  • name — Human-readable identifier (for your dashboard)
  • tasks — Array of task objects

Optional fields:

  • priority — “low”, “normal”, “high” (default: “normal”)
  • tags — Array of strings for organizing jobs (e.g., ["ml", "production"])
  • metadata — Custom key-value pairs (up to 1KB)

Task Structure

Each task must have:

{
  "id": "unique-task-id",
  "prompt": "What you want the miner to generate",
  "timeout_ms": 30000
}

Required fields:

  • id — Unique within the job (letters, numbers, hyphens)
  • prompt — Your instruction (can be 1 line or 1000 lines)
  • timeout_ms — Max execution time in milliseconds

Optional fields:

  • depends_on — Array of task IDs this task depends on (default: [])
  • max_retries — Retry up to N times on failure (default: 0)
  • resources — Resource requirements (see below)
  • priority — “low”, “normal”, “high” (overrides job priority)

Resource Specification

Tell Swarmient what hardware your task needs:

{
  "id": "gpu-inference",
  "prompt": "Run inference on this model using a GPU",
  "timeout_ms": 120000,
  "resources": {
    "gpu": "required",
    "memory_gb": 8,
    "cpu_cores": 4
  }
}

Available fields:

  • gpu — "required" or "optional" (default: "optional")
  • memory_gb — Minimum RAM in GB, 1–1024 (default: 4)
  • cpu_cores — Minimum CPU cores, 1–128 (default: 2)

Tips:

  • Only request GPU if your task actually needs it (GPU time is expensive)
  • For ML workloads, 8–16GB memory is usually enough
  • For standard tasks, 2–4 CPU cores is fine

Submitting a Job

Use the /v1/jobs/submit endpoint:

curl -X POST https://api.swarmient.com/v1/jobs/submit \
  -H "Authorization: Bearer $SWARMIENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "generate-api",
    "tasks": [
      {
        "id": "task-1",
        "prompt": "Write a REST API in Python using FastAPI",
        "timeout_ms": 60000
      }
    ]
  }'

Response:

{
  "job_id": "job_abc123def456",
  "status": "PENDING",
  "created_at": "2026-07-08T12:00:00Z",
  "estimated_cost": 0.08
}

Streaming Results

After submission, you can stream results as they complete:

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

You’ll get results as server-sent events (SSE):

data: {"event": "task_started", "task_id": "task-1", "miner_id": "miner_xyz789"}
data: {"event": "task_completed", "task_id": "task-1", "result": "...", "execution_time_ms": 2340}
data: {"event": "job_completed", "total_cost": 0.08}

This is great for real-time monitoring or integrating into your application.

Polling for Results

If you prefer polling instead of streaming:

# Check status repeatedly
curl https://api.swarmient.com/v1/jobs/job_abc123def456 \
  -H "Authorization: Bearer $SWARMIENT_API_KEY"

Response includes full job state:

{
  "job_id": "job_abc123def456",
  "status": "COMPLETED",
  "tasks": [
    {
      "id": "task-1",
      "status": "COMPLETED",
      "result": "from fastapi import FastAPI\napp = FastAPI()\n...",
      "miner_id": "miner_xyz789",
      "execution_time_ms": 2340,
      "cost": 0.08,
      "proof": {
        "signature": "...",
        "miner_public_key": "..."
      }
    }
  ],
  "total_cost": 0.08
}

Complex Workflows

Here’s a realistic multi-task workflow:

{
  "name": "build-service",
  "priority": "high",
  "tasks": [
    {
      "id": "design-schema",
      "prompt": "Design a PostgreSQL schema for an e-commerce platform with users, products, orders, and payments",
      "timeout_ms": 45000,
      "depends_on": []
    },
    {
      "id": "generate-api",
      "prompt": "Write a Go REST API using the Echo framework that implements CRUD operations for the schema from task 'design-schema'",
      "timeout_ms": 90000,
      "depends_on": ["design-schema"],
      "resources": {
        "memory_gb": 8
      }
    },
    {
      "id": "write-tests",
      "prompt": "Write comprehensive Go tests for the API from task 'generate-api' using testify",
      "timeout_ms": 60000,
      "depends_on": ["generate-api"],
      "max_retries": 2
    },
    {
      "id": "generate-docs",
      "prompt": "Write OpenAPI 3.0 documentation for the API from task 'generate-api'",
      "timeout_ms": 30000,
      "depends_on": ["generate-api"]
    },
    {
      "id": "docker",
      "prompt": "Create a production-grade Dockerfile for the API from task 'generate-api'",
      "timeout_ms": 30000,
      "depends_on": ["generate-api"]
    }
  ]
}

Execution flow:

  1. design-schema runs (0 dependencies)
  2. Once design-schema completes, generate-api starts
  3. Once generate-api completes, write-tests, generate-docs, and docker all run in parallel
  4. Job completes once all tasks finish

This job requests a full e-commerce service architecture in minutes, with parallelization where possible.

Error Handling

Every task can fail for various reasons. The response includes an error field:

{
  "id": "task-1",
  "status": "FAILED",
  "error": {
    "code": "TIMEOUT",
    "message": "Task exceeded 30000ms timeout"
  }
}

Common error codes:

  • TIMEOUT — Task didn’t finish in time
  • INVALID_PROMPT — Prompt was empty or malformed
  • MINER_DISCONNECTED — Miner crashed or went offline
  • INSUFFICIENT_RESOURCES — No miners had the resources you requested
  • SANDBOX_ERROR — Something went wrong in the miner’s sandbox

If a task fails:

  • Dependent tasks are skipped (they can’t run without input)
  • You’re not charged for the failed task (or only for work that completed)
  • You can resubmit the job to retry

Best Practices

Be Specific in Prompts

Good prompt:

Write a Python function that takes a list of integers and returns them sorted in ascending order. Include type hints. Make it efficient (O(n log n) or better).

Vague prompt:

Write Python code

Handle Large Outputs

Results can be large (generated code, models, etc.). If a result is > 1MB, you’ll get:

{
  "result": "... first 100KB of output ...",
  "result_truncated": true,
  "full_result_url": "https://api.swarmient.com/v1/jobs/job_xyz/tasks/task-1/result"
}

Fetch the full result from the URL:

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

Set Realistic Timeouts

  • 30 seconds: Simple code generation (a function, a class)
  • 60 seconds: Medium code (an API endpoint, a utility module)
  • 120 seconds: Complex code (a full service, with tests)
  • 300+ seconds: Very complex workflows (model training, large system design)

If you’re unsure, start with 60 seconds and increase if tasks time out.

Use Tags for Organization

Tag your jobs so you can find them later:

{
  "name": "weekly-pipeline",
  "tags": ["ml", "production", "weekly"],
  "tasks": [...]
}

Then search your dashboard by tag.

Monitor Costs

Every job response includes estimated_cost before execution and total_cost after completion:

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

Large jobs can be expensive. Always check the cost before submitting complex workflows.

Next Steps