One-Off Jobs

There are times when you want to run a specific task to completion, or run many such tasks in parallel with different arguments. You still want to use the same build your Render service is using, and potentially override some environment variables. This can be useful if you want to run database migrations, recompile assets, and more. Render Jobs help you do just that.

Creating a job

You can create a job with the Render API by making a POST request to the /services/{service-id}/jobs endpoint. You can find the complete job schema and learn more about the API (including how to authenticate) in our API documentation.

A job can be based on an existing web service, private service, background worker, or cron job. You do not need to create a new service just to run a job.

curl --request POST 'https://api.render.com/v1/services/crn-c24q2tmcie6so2aq3n90/jobs' \
    --header 'Authorization: Bearer API_TOKEN' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "startCommand": "echo hi"
    }'

Once you create a job, it will be in a pending state with no status, startedAt, or finishedAt:

{
  "id": "job-c3rfdgg6n88pa7t3a6ag",
  "serviceId": "crn-c24q2tmcie6so2aq3n90",
  "startCommand": "echo hi",
  "planId": "plan-crn-002",
  "createdAt": "2021-07-20T12:16:02.544199-04:00",
  "startedAt": null,
  "finishedAt": null,
  "status": null
}

You can poll for a job’s status using the API:

curl --request GET 'https://api.render.com/v1/services/crn-c24q2tmcie6so2aq3n90/jobs/job-c3rfdgg6n88pa7t3a6ag' \
    --header 'Authorization: Bearer API_TOKEN'

Once a job starts running, the startedAt timestamp will be populated. Upon completion, the finishedAt timestamp will be populated, and the job will have a status of succeeded or failed.

{
  "id": "job-c3rfdgg6n88pa7t3a6ag",
  "serviceId": "crn-c24q2tmcie6so2aq3n90",
  "startCommand": "echo hi",
  "planId": "plan-crn-002",
  "createdAt": "2021-07-15T07:20:05.777035-07:00",
  "startedAt": "2021-07-15T07:24:12.987032-07:00",
  "finishedAt": "2021-07-15T07:27:14.234587-07:00",
  "status": "succeeded"
}

You can list jobs by service using the /services/{service-id}/jobs endpoint.

Jobs can also be viewed in the dashboard on the corresponding service page:

Environment

A job will use the last successful build of the service it is created from, and will have access to any environment variables that are configured for that service at the time that the job is created.

Instance Types and Pricing

By default, a job will adopt the instance type that is configured for a service. A job is billed the per-second equivalent of that plan’s monthly rate.

You can override the instance type that is used for a job by passing a planId on job creation. If overriding a job’s plan, you must use a instance type that corresponds to the base service type (for example, a job created based on a cron job must use a cron job plan, and cannot use a web service plan). Available instance types are:

Web Services, Private Services, and Background Workers

Cron Jobs

Logs

Job logs are available through log streams, and a job’s most recent logs can be viewed in the dashboard.

Notes

• A job times out after 30 days if its command doesn’t complete/exit.
• Running jobs are not interrupted by new deploys or suspending the service.
• A job can’t access its base service’s persistent disk (if it has one).