Workers

Workers are background job processors that run continuously without exposing HTTP endpoints. Use workers for queue processing, scheduled tasks, and other background work.

Endpoints

Method	Endpoint	Description
`GET`	`/api/workers/`	List all your workers
`POST`	`/api/workers/`	Create a new worker
`GET`	`/api/workers/{id}/`	Get worker details
`PATCH`	`/api/workers/{id}/`	Update a worker
`DELETE`	`/api/workers/{id}/`	Delete a worker

Worker Object

json

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "email-processor",
  "image": "myapp/worker:v1.0.0",
  "replicas_target": 2,
  "replicas_running": 2,
  "status": "ready",
  "config": "config-uuid",
  "secret": "secret-uuid",
  "deploy_successful": true,
  "created_at": "2024-10-15T10:00:00Z",
  "updated_at": "2024-10-15T12:00:00Z"
}

Fields

Field	Type	Description
`id`	UUID	Unique identifier (read-only)
`name`	string	Worker name (max 32 characters, unique per account)
`image`	string	Docker image to run
`replicas_target`	integer	Desired number of instances (1-12)
`replicas_running`	integer	Currently running instances (read-only)
`status`	string	Current status (read-only)
`config`	UUID	Configuration to attach
`secret`	UUID	Secret to attach
`deploy_successful`	boolean	Whether last deployment succeeded (read-only)

Workers vs Services

Feature	Service	Worker
HTTP endpoint	Yes (port required)	No
Can be routed to	Yes	No
Use case	Web apps, APIs	Background jobs
Kubernetes resource	Deployment + Service	Deployment only

When to Use Workers

Queue processors (Celery, RabbitMQ consumers)
Scheduled tasks and cron jobs
Data processing pipelines
Event handlers
Stream processors
Long-running background tasks

List Workers

http

GET /api/workers/

Example:

bash

curl -H "Authorization: Bearer gob_your_key" \
  https://api.example.com/api/workers/

Response:

json

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "abc123...",
      "name": "email-processor",
      "image": "myapp/worker:v1.0.0",
      "replicas_target": 2,
      "replicas_running": 2,
      "status": "ready"
    },
    {
      "id": "def456...",
      "name": "data-pipeline",
      "image": "myapp/pipeline:v2.0.0",
      "replicas_target": 1,
      "replicas_running": 1,
      "status": "ready"
    }
  ]
}

Create Worker

http

POST /api/workers/

Request Body:

json

{
  "name": "email-processor",
  "image": "myapp/worker:v1.0.0",
  "replicas_target": 2,
  "config": "config-uuid",
  "secret": "secret-uuid"
}

Required Fields:

name - Unique name (letters, numbers, hyphens only)
image - Docker image to run
config - ID of a configuration you own
secret - ID of a secret you own

Optional Fields:

replicas_target - Number of instances (default: 1, max: 12)

Example:

bash

curl -X POST https://api.example.com/api/workers/ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "email-processor",
    "image": "myapp/worker:v1.0.0",
    "replicas_target": 3,
    "config": "7a6b5c4d-...",
    "secret": "8b7c6d5e-..."
  }'

Response (201 Created):

json

{
  "id": "xyz789...",
  "name": "email-processor",
  "image": "myapp/worker:v1.0.0",
  "replicas_target": 3,
  "replicas_running": 0,
  "status": "pending",
  "deploy_successful": false
}

Get Worker

http

GET /api/workers/{id}/

Example:

bash

curl -H "Authorization: Bearer gob_your_key" \
  https://api.example.com/api/workers/xyz789.../

Update Worker

http

PATCH /api/workers/{id}/

Updatable Fields:

image - Deploy a new version
replicas_target - Scale up or down

Example - Update Image:

bash

curl -X PATCH https://api.example.com/api/workers/xyz789.../ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"image": "myapp/worker:v1.1.0"}'

Example - Scale Worker:

bash

curl -X PATCH https://api.example.com/api/workers/xyz789.../ \
  -H "Authorization: Bearer gob_your_key" \
  -H "Content-Type: application/json" \
  -d '{"replicas_target": 5}'

Delete Worker

http

DELETE /api/workers/{id}/

Example:

bash

curl -X DELETE https://api.example.com/api/workers/xyz789.../ \
  -H "Authorization: Bearer gob_your_key"

Response: 204 No Content

Quotas

Workers count towards the same quotas as services:

Service quota - Total services + workers
Replica quota - Total replicas across all services and workers

Quota Exceeded (400):

json

{
  "error": "Service quota exceeded. Maximum 10 services allowed.",
  "quota": {
    "current": 10,
    "max": 10
  }
}

Common Use Cases

Celery Worker

bash

curl -X POST https://api.example.com/api/workers/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "celery-worker",
    "image": "myapp:v1.0.0",
    "replicas_target": 4,
    "config": "'$CONFIG_ID'",
    "secret": "'$SECRET_ID'"
  }'

Your Docker image should start Celery:

dockerfile

CMD ["celery", "-A", "myapp", "worker", "--loglevel=info"]

Scheduled Task Runner

bash

curl -X POST https://api.example.com/api/workers/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "scheduler",
    "image": "myapp:v1.0.0",
    "replicas_target": 1,
    "config": "'$CONFIG_ID'",
    "secret": "'$SECRET_ID'"
  }'

Data Pipeline

bash

curl -X POST https://api.example.com/api/workers/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-processor",
    "image": "myapp/pipeline:v1.0.0",
    "replicas_target": 2,
    "config": "'$CONFIG_ID'",
    "secret": "'$SECRET_ID'"
  }'

Example Workflow

Deploy a Complete Application

Deploy both a web service and its background workers:

bash

# 1. Get config and secret IDs
CONFIG_ID=$(curl -s -H "Authorization: Bearer $API_KEY" \
  https://api.example.com/api/configs/ | jq -r '.results[0].id')

SECRET_ID=$(curl -s -H "Authorization: Bearer $API_KEY" \
  https://api.example.com/api/secrets/ | jq -r '.results[0].id')

# 2. Deploy the web service
curl -X POST https://api.example.com/api/services/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myapp-web",
    "image": "myapp:v1.0.0",
    "port": 8080,
    "replicas_target": 3,
    "config": "'$CONFIG_ID'",
    "secret": "'$SECRET_ID'"
  }'

# 3. Deploy the worker
curl -X POST https://api.example.com/api/workers/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myapp-worker",
    "image": "myapp:v1.0.0",
    "replicas_target": 2,
    "config": "'$CONFIG_ID'",
    "secret": "'$SECRET_ID'"
  }'

Next Steps

Services - Deploy web applications
Configs - Configure your workers
Secrets - Manage worker secrets

Workers ​

Endpoints ​

Worker Object ​

Fields ​

Workers vs Services ​

When to Use Workers ​

List Workers ​

Create Worker ​

Get Worker ​

Update Worker ​

Delete Worker ​

Quotas ​

Common Use Cases ​

Celery Worker ​

Scheduled Task Runner ​

Data Pipeline ​

Example Workflow ​

Deploy a Complete Application ​

Next Steps ​

Workers

Endpoints

Worker Object

Fields

Workers vs Services

When to Use Workers

List Workers

Create Worker

Get Worker

Update Worker

Delete Worker

Quotas

Common Use Cases

Celery Worker

Scheduled Task Runner

Data Pipeline

Example Workflow

Deploy a Complete Application

Next Steps