> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.labric.co/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.labric.co/_mcp/server.

# Start a job execution

POST https://platform.labric.co/api/v1/job-executions
Content-Type: application/json

Open a job execution for a script running outside the platform.

Pass the returned job_execution_id to the write and upload-file tools so
everything one script run produces is attributed to a single execution and
can be inspected or reverted as a unit. Pass job_id to run under an
existing job, job_name to run under a job of that name (created if
missing), or neither to run under the default off-platform job.

The execution is marked running immediately. Close it as completed or
failed when the script finishes. Pass timeout_minutes to have the platform
fail it after that long if the script has not closed it, so a crashed
script does not leave it running forever.

Requires an API key with the `write` scope.

Reference: https://docs.labric.co/api-reference/labric-api/jobs/start

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Body (application/json)

This endpoint expects an object.

- `job_id` (string, optional, nullable) — ID of an existing job to run under. Omit to use job_name instead.
- `job_name` (string, optional, nullable) — Name of the job to run under, created if it does not exist yet. Ignored when job_id is given. Defaults to 'Off-Platform Manual Job'.
- `timeout_minutes` (integer, optional, nullable) — Fail the execution if the script has not closed it within this many minutes (at most 43200, i.e. 30 days), so a crashed script does not leave it running forever. Omit to let it run until closed.

## Response

### 200

OK

- `job_execution_id` (string, required) — Pass this as job_execution_id to the write and upload-file tools.
- `job_id` (string, required) — ID of the job the execution belongs to.
- `job_name` (string, required) — Name of the job the execution belongs to.
- `status` (string, required, nullable) — The execution's current status.
- `started_at` (datetime, required, nullable) — When the execution started.
- `completed_at` (datetime, required, nullable) — When the execution ended, or null while it is still running.

## Errors

### 400 Bad Request Error

Bad Request

- `detail` (string, required)

### 401 Unauthorized Error

Unauthorized

- `detail` (string, required)

### 403 Forbidden Error

Forbidden

- `detail` (string, required)

### 404 Not Found Error

Not Found

- `detail` (string, required)

### 422 Unprocessable Entity Error

Unprocessable Content

- `detail` (list of map from string to any, required)

### 500 Internal Server Error

Internal Server Error

- `detail` (string, required)

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "job_execution_id": "string",
  "job_id": "string",
  "job_name": "string",
  "status": "string",
  "started_at": "2024-01-15T09:30:00Z",
  "completed_at": "2024-01-15T09:30:00Z"
}
```

**SDK Code**

```python
from labric import Labric, StartJobExecutionSchema

client = Labric(
    api_key="YOUR_TOKEN_HERE",
)

client.jobs.start(
    request=StartJobExecutionSchema(),
)

```