Jobs API reference

Detailed documentation on the jobs API

With the jobs API, you can schedule jobs and tasks in the future.

The HTTP APIs are intended for development and testing only. For production scenarios, the use of the SDKs is strongly recommended as they implement the gRPC APIs providing higher performance and capability than the HTTP APIs.

Schedule a job

Schedule a job with a name.

POST http://localhost:3500/v1.0-alpha1/jobs/<name>

URL parameters

Parameter Description
name Name of the job you’re scheduling
data A JSON serialized value or object.
schedule An optional schedule at which the job is to be run. Details of the format are below.
dueTime An optional time at which the job should be active, or the “one shot” time, if other scheduling type fields are not provided. Accepts a “point in time” string in the format of RFC3339, Go duration string (calculated from creation time), or non-repeating ISO8601.
repeats An optional number of times in which the job should be triggered. If not set, the job runs indefinitely or until expiration.
ttl An optional time to live or expiration of the job. Accepts a “point in time” string in the format of RFC3339, Go duration string (calculated from job creation time), or non-repeating ISO8601.

schedule

schedule accepts both systemd timer-style cron expressions, as well as human readable ‘@’ prefixed period strings, as defined below.

Systemd timer style cron accepts 6 fields:

seconds minutes hours day of month month day of week
0-59 0-59 0-23 1-31 1-12/jan-dec 0-6/sun-sat
Example 1

“0 30 * * * *” - every hour on the half hour

Example 2

“0 15 3 * * *” - every day at 03:15

Period string expressions:

Entry Description Equivalent To
@every Run every (e.g. ‘@every 1h30m’) N/A
@yearly (or @annually) Run once a year, midnight, Jan. 1st 0 0 0 1 1 *
@monthly Run once a month, midnight, first of month 0 0 0 1 * *
@weekly Run once a week, midnight on Sunday 0 0 0 * * 0
@daily (or @midnight) Run once a day, midnight 0 0 0 * * *
@hourly Run once an hour, beginning of hour 0 0 * * * *

Request body

{
  "data": "some data",
  "dueTime": "30s"
}

HTTP response codes

Code Description
204 Accepted
400 Request was malformed
500 Request formatted correctly, error in dapr code or Scheduler control plane service

Response content

The following example curl command creates a job, naming the job jobforjabba and specifying the schedule, repeats and the data.

$ curl -X POST \
  http://localhost:3500/v1.0-alpha1/jobs/jobforjabba \
  -H "Content-Type: application/json" \
  -d '{
        "data": "{\"value\":\"Running spice\"}",
        "schedule": "@every 1m",
        "repeats": 5
    }'

Get job data

Get a job from its name.

GET http://localhost:3500/v1.0-alpha1/jobs/<name>

URL parameters

Parameter Description
name Name of the scheduled job you’re retrieving

HTTP response codes

Code Description
200 Accepted
400 Request was malformed
500 Request formatted correctly, Job doesn’t exist or error in dapr code or Scheduler control plane service

Response content

After running the following example curl command, the returned response is JSON containing the name of the job, the dueTime, and the data.

$ curl -X GET http://localhost:3500/v1.0-alpha1/jobs/jobforjabba -H "Content-Type: application/json"

{
  "name": "jobforjabba",
  "schedule": "@every 1m",
  "repeats": 5,
  "data": 123
}

Delete a job

Delete a named job.

DELETE http://localhost:3500/v1.0-alpha1/jobs/<name>

URL parameters

Parameter Description
name Name of the job you’re deleting

HTTP response codes

Code Description
204 Accepted
400 Request was malformed
500 Request formatted correctly, error in dapr code or Scheduler control plane service

Response content

In the following example curl command, the job named test1 with app-id sub will be deleted

$ curl -X DELETE http://localhost:3500/v1.0-alpha1/jobs/jobforjabba -H "Content-Type: application/json"

Next steps

Jobs API overview


Last modified December 18, 2024: Merge pull request #4461 from dapr/dependabot/npm_and_yarn/daprdocs/nanoid-3.3.8 (5660a64)