One-Off Jobs

Sometimes it's useful to spin up a short-lived process to run a specific task, such as asset compilation or a database migration. You can do this on Render by creating a one-off job.

A one-off job uses the same build artifact and configuration as one of your existing Render services (this is the job's base service). This means the job can execute any of the base service's defined scripts and access its environment variables.

A one-off job cannot access its base service's persistent disk (if it has one).

While a one-off job is running, it's billed at the per-second rate for its specified compute plan.

Running a one-off job

You create a one-off job with Render API's Create job endpoint.

New to the Render API? Get started.

This example curl command creates a one-off job that runs the command echo hi and exits:

To try out this example, substitute your service ID and API key where indicated.

• Your service ID is available in the Render Dashboard. Navigate to your service's page and copy the ID from the URL in your browser.
  • This value starts with crn- for cron jobs and srv- for other service types.
• Learn how to create an API key.

The Create job endpoint requires a startCommand parameter, which specifies the command Render will run to start the job.

You can optionally specify a planId to use a different compute plan from the job's base service. See supported compute plans.

Build and environment

On creation, a one-off job obtains the following values from its base service:

• The base service's most recent successful build artifact
• All of the base service's configured environment variables

A job uses this "snapshot" of the base service for its own execution. If these values later change in the base service, existing jobs are not affected.

Response format

If creation succeeds, the Create job endpoint returns a JSON object with the following fields:

Next, you can track the job's progress.

Tracking job progress

You can track a one-off job's progress in the Render Dashboard or via the Render API. Logs generated by one-off jobs are also included in your workspace's log stream.

Select a tab for details:

Terminating a job

• A one-off job terminates whenever its specified startCommand exits. Render automatically deprovisions the job's instance.
• You can terminate a one-off job manually with the Cancel running job endpoint.
• If a one-off job hasn't exited after 30 days, Render automatically terminates it.
• If you redeploy or suspend the base service of a running one-off job, the job is not terminated. It continues running using its existing build artifact and configuration.

Compute plan IDs

By default, a one-off job uses the same compute plan as its base service and is billed accordingly. You can use a different compute plan by providing a planId parameter to the Create job endpoint. This is most commonly useful for running basic tasks on lower-cost compute.

See below for supported values of planId according to your base service's type:

Cron jobs

These compute plan IDs apply only to cron job services.

All other service types

These service type IDs apply to web services, private services, and background workers.