# 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](disks) (if it has one).

While a one-off job is running, it's billed at the per-second rate for its specified [instance type](#instance-type-ids).

## Running a one-off job

You create a one-off job with Render API's [Create job](https://api-docs.render.com/reference/post-job) endpoint.

> *New to the Render API?* [Get started.](api)

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

```bash
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][dboard]. 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](api#1-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](#instance-type-ids).

### 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](configure-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](https://api-docs.render.com/reference/post-job) returns a JSON object with the following fields:

```json
{
  "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).

### 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](log-streams).

Select a tab for details:

**API**

You can poll for a job's status using the Render API's [Retrieve job](https://api-docs.render.com/reference/retrieve-job) endpoint:

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

This endpoint's response includes timestamps for when the job started and finished, along with its status:

```json
{
  "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", // highlight-line
  "finishedAt": "2025-03-20T07:27:14.234587-07:00", // highlight-line
  "status": "succeeded" // highlight-line
}
```

You can also list a service's jobs (with optional filters) using the [List jobs](https://api-docs.render.com/reference/list-job) endpoint.

**Dashboard**

In the [Render Dashboard][dboard], you can view the details of current and past one-off jobs from your base service's **Jobs** page:

[img]

This page also displays the logs for recent job runs. Render retains logs for one-off jobs according to your workspace's [log retention period](logging#retention-period).

### 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](https://api-docs.render.com/reference/cancel-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.

## 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](https://api-docs.render.com/reference/post-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.

| Instance Type ID | Instance Type | Specs |
|--------|--------|--------|
| `plan-crn-003` | Starter | 512 MB RAM 0.5 CPU |
| `plan-crn-005` | Standard | 2 GB RAM 1 CPU |
| `plan-crn-007` | Pro | 4 GB RAM 2 CPU |
| `plan-crn-008` | Pro Plus | 8 GB RAM 4 CPU |

### All other service types

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

| Instance Type ID | Instance Type | Specs |
|--------|--------|--------|
| `plan-srv-006` | Starter | 512 MB RAM 0.5 CPU |
| `plan-srv-008` | Standard | 2 GB RAM 1 CPU |
| `plan-srv-010` | Pro | 4 GB RAM 2 CPU |
| `plan-srv-011` | Pro Plus | 8 GB RAM 4 CPU |
| `plan-srv-013` | Pro Max | 16 GB RAM 4 CPU |
| `plan-srv-014` | Pro Ultra | 32 GB RAM 8 CPU |