Jobs API reference

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. This is because HTTP does JSON marshalling which can be expensive, while with gRPC, the data is transmitted over the wire and stored as-is being more performant.

Schedule a job

Schedule a job with a name. Jobs are scheduled based on the clock of the server where the Scheduler service is running. The timestamp is not converted to UTC. You can provide the timezone with the timestamp in RFC3339 format to specify which timezone you’d like the job to adhere to. If no timezone is provided, the server’s local time is used.

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

URL parameters

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:

Example 1

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

Example 2

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

Period string expressions:

failure_policy

failure_policy specifies how the job should handle failures.

It can be set to constant or drop.

• The constant policy retries the job constantly with the following configuration options.
  • max_retries configures how many times the job should be retried. Defaults to retrying indefinitely. nil denotes unlimited retries, while 0 means the request will not be retried.
  • interval configures the delay between retries. Defaults to retrying immediately. Valid values are of the form 200ms, 15s, 2m, etc.
• The drop policy drops the job after the first failure, without retrying.

Example 1

{
  //...
  "failure_policy": {
    "constant": {
      "max_retries": 3,
      "interval": "10s"
    }
  }
}

Example 2

{
  //...
  "failure_policy": {
    "drop": {}
  }
}

Request body

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

HTTP response codes

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:<daprPort>/v1.0-alpha1/jobs/<name>

URL parameters

HTTP response codes

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:<daprPort>/v1.0-alpha1/jobs/<name>

URL parameters

HTTP response codes

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