Skip to main content

Managing Jobs

Managing Jobs​

Get a Job​

curl -X POST https://api.travila.ai/api/v1/scheduler/get-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{ "schedule_id": "sched_a1b2c3d4e5f60718" }'

List Jobs​

Returns all jobs for the authenticated tenant and project. Optionally filter by state or target kind.

curl -X POST https://api.travila.ai/api/v1/scheduler/list-jobs \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "page_size": 20,
    "state_filter": "SCHEDULE_STATE_ACTIVE"
  }'

Update a Job​

Partial update — only the fields you include are changed. Omitted fields are left unchanged.

curl -X POST https://api.travila.ai/api/v1/scheduler/update-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_id": "sched_a1b2c3d4e5f60718",
    "cron_expression": "0 10 * * 1-5"
  }'
Cron expression changes

Cron expression updates may not take effect until the next worker deployment. Check effective_at in the response — it will say either immediate or next_worker_deployment.

Pause and Resume​

Use pause to temporarily stop a job without deleting it. Resume returns it to SCHEDULE_STATE_ACTIVE.

# Pause
curl -X POST https://api.travila.ai/api/v1/scheduler/pause-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_id": "sched_a1b2c3d4e5f60718",
    "reason": "Target service under maintenance"
  }'

# Resume
curl -X POST https://api.travila.ai/api/v1/scheduler/resume-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "schedule_id": "sched_a1b2c3d4e5f60718" }'

Delete a Job​

Soft-delete — the job stops firing immediately. Deleted jobs are retained for audit and can still be retrieved by ID.

curl -X POST https://api.travila.ai/api/v1/scheduler/delete-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{ "schedule_id": "sched_a1b2c3d4e5f60718" }'

Referencing Jobs by External ID​

Every job has a server-assigned schedule_id (prefixed sched_). You can also attach your own external_id at creation — a stable identifier from your own system, unique within your tenant and project, and immutable once set.

curl -X POST https://api.travila.ai/api/v1/scheduler/create-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily digest",
    "schedule_type": "SCHEDULE_TYPE_CRON",
    "cron_expression": "0 9 * * 1-5",
    "external_id": "user-42-daily-digest",
    "target": { "url": "https://your-api.example.com/jobs/daily-digest", "kind": "digest" }
  }'

Once set, get-job, update-job, pause-job, resume-job, and delete-job accept external_id in place of schedule_id — provide exactly one of the two. This lets you address a job by your own key without first storing the generated schedule_id.

curl -X POST https://api.travila.ai/api/v1/scheduler/get-job \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "user-42-daily-digest" }'
note

external_id must not start with the reserved sched_ prefix, and cannot be changed after the job is created.