Jobs

Create and manage scheduled HTTP jobs with cron expressions, recurring intervals, or one-time triggers.

A job is a saved HTTP request definition with a schedule. When the schedule fires, TrigRun makes the HTTP request and records the result.

Job kinds

Kind	Schedule	Use case
`recurring`	Every N minutes (1–1440)	Periodic health checks, sync endpoints
`cron`	5-field cron expression with timezone	Nightly backups, weekly reports, complex schedules
`scheduled`	One run at a future timestamp	Delayed actions, scheduled launches
`one_time`	Immediate, single execution	Webhooks, one-shot triggers

Creating a job

Recurring job

Runs every N minutes, starting from creation time:

curl -X POST https://api.trigrun.com/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sync-inventory",
    "kind": "recurring",
    "schedule": {
      "every_n_minutes": 15,
      "timezone": "UTC"
    },
    "request": {
      "url": "https://api.example.com/sync",
      "method": "POST",
      "headers": {
        "Authorization": "secret://api-key"
      },
      "timeout_seconds": 60
    }
  }'

Cron job

Uses standard 5-field cron syntax. Timezone defaults to UTC if not specified.

curl -X POST https://api.trigrun.com/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-report",
    "kind": "cron",
    "schedule": {
      "cron": "30 9 * * 1-5",
      "timezone": "America/New_York"
    },
    "request": {
      "url": "https://api.example.com/report",
      "method": "POST"
    }
  }'

Cron field reference:

┌──────── minute (0-59)
│ ┌────── hour (0-23)
│ │ ┌──── day of month (1-31)
│ │ │ ┌── month (1-12)
│ │ │ │ ┌ day of week (0-7, Sun=0 or 7)
│ │ │ │ │
* * * * *

Common patterns:

Expression	Meaning
`* * * * *`	Every minute
`0 * * * *`	Every hour
`0 2 * * *`	Daily at 2:00 AM
`30 9 * * 1-5`	Weekdays at 9:30 AM
`0 0 1 * *`	First day of every month at midnight

One-time immediate

Creates a job and immediately queues an execution:

curl -X POST https://api.trigrun.com/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "deploy-hook",
    "kind": "one_time",
    "request": {
      "url": "https://api.example.com/deploy",
      "method": "POST",
      "body": "{\"version\": \"1.2.3\"}"
    }
  }'

Job states

State	Meaning
`active`	Scheduled and will run at `next_run_at`
`paused`	Schedule suspended, won't run until resumed
`draft`	Created but not yet activated
`completed`	Terminal state for one-time/scheduled jobs after execution

Pause and resume

# Pause
curl -X POST https://api.trigrun.com/v1/jobs/JOB_ID/pause \
  -H "Authorization: Bearer $TOKEN"

# Resume
curl -X POST https://api.trigrun.com/v1/jobs/JOB_ID/resume \
  -H "Authorization: Bearer $TOKEN"

Resuming a job recomputes next_run_at from the current time.

Request configuration

Field	Type	Default	Description
`url`	string	(required)	Target URL. Must be publicly reachable HTTP/HTTPS.
`method`	string	`GET`	HTTP method: GET, POST, PUT, PATCH, DELETE
`headers`	object	`{}`	Key-value pairs. Supports `secret://name` syntax.
`body`	any	null	Request body. Sent as-is.
`timeout_seconds`	integer	`30`	Request timeout (1–300 seconds).
`success_statuses`	integer[]	`[200, 201, 202, 204]`	Status codes considered successful.

Retry policy

Field	Type	Default	Description
`max_attempts`	integer	`3`	Total attempts including the first (1–10).
`retry_on_statuses`	integer[]	`[429, 500, 502, 503, 504]`	Status codes that trigger a retry.

Retries use exponential backoff: 250ms * 2^attempt with jitter.

Secret references in headers

You can reference workspace secrets in job headers using secret://name:

{
  "headers": {
    "Authorization": "Bearer secret://stripe-key",
    "X-Custom-Header": "secret://custom-token"
  }
}

At execution time, TrigRun resolves secret://stripe-key to the decrypted secret value. See the Secrets guide for how to create and manage secrets.

Updating a job

Use PATCH to update specific fields:

curl -X PATCH https://api.trigrun.com/v1/jobs/JOB_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "updated-name",
    "schedule": { "every_n_minutes": 30 }
  }'

You can update the name, kind, schedule, request, retry policy, state, and concurrency limit in a single request. Only include the fields you want to change.

Triggering manually

Run a job immediately regardless of its schedule:

curl -X POST https://api.trigrun.com/v1/jobs/JOB_ID/run-now \
  -H "Authorization: Bearer $TOKEN"

This creates a new execution with source: "manual". The job's regular schedule is unaffected.

Bulk import from crontab

Import jobs from standard crontab format:

curl -X POST https://api.trigrun.com/v1/jobs/import \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "crontab": "*/5 * * * * https://api.example.com/health\n0 2 * * * https://api.example.com/cleanup",
    "default_url": "https://api.example.com/fallback"
  }'

Each line follows standard crontab format: <cron-expression> <url>. Lines starting with # are ignored. If a line doesn't contain a URL, the default_url is used.

Idempotent creation

To avoid duplicate jobs, pass an Idempotency-Key header:

curl -X POST https://api.trigrun.com/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-v1.2.3" \
  -d '{ ... }'

If a job with the same idempotency key already exists in the workspace, the existing job is returned instead of creating a duplicate.

Deleting a job

curl -X DELETE https://api.trigrun.com/v1/jobs/JOB_ID \
  -H "Authorization: Bearer $TOKEN"

Deleting a job also deletes its executions and notification rules.

CLI reference

cronctl jobs list                       # List all jobs
cronctl jobs list --state active        # Filter by state
cronctl jobs get JOB_ID                 # Get job details
cronctl jobs create --name my-job \
  --url https://example.com \
  --kind cron --cron "0 * * * *"        # Create cron job
cronctl jobs pause JOB_ID               # Pause
cronctl jobs resume JOB_ID              # Resume
cronctl jobs run JOB_ID                 # Trigger now
cronctl jobs delete JOB_ID              # Delete

Jobs

On this page