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.

While a one-off job is running, it’s billed at the per-second rate for its specified instance type.

Running a one-off job

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

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

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

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 instance type from the job’s base service. See supported instance types.

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:

{
  "id": "job-c3rfdgg6n88pa7t3a6ag",
  "serviceId": "crn-c24q2tmcie6so2aq3n90",
  "startCommand": "echo hi",
  "planId": "plan-crn-002",
  "createdAt": "2025-03-20T12:16:02.544199-04:00"
}

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:

curl --request GET 'https://api.render.com/v1/services/YOUR_SERVICE_ID/jobs/YOUR_JOB_ID' \
    --header 'Authorization: Bearer YOUR_API_KEY'

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

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, or from the base service’s Jobs page in the Render Dashboard.
• 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.

Instance type IDs

By default, a one-off job uses the same instance type as its base service and is billed accordingly. You can use a different instance type 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 instance type IDs apply only to cron job services.

All other service types

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