> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ns.rocks/llms.txt
> Use this file to discover all available pages before exploring further.

# Runs And Artifacts

> Manage async code runs and files produced by code execution.

<Warning>
  Queued async code run creation, waiting, and cancellation are not part of the
  hosted private beta launch surface. Remote host-agent routing for queued code
  runs is not implemented yet, so use `machine.run_code()` or
  `machine.code_interpreter.run_code()` for hosted beta workloads.
</Warning>

`list_runs()` is available for read-only hosted beta inspection. The mutation
snippets below document the queued-run API shape for local/self-hosted control
planes that can route the assigned runtime host. They are not acceptance
criteria for hosted private beta.

## Future queued run mutations

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
ctx = machine.code_interpreter.create_code_context(cwd="/workspace")
run = machine.code_interpreter.create_run(
    "import time\nfor i in range(5): time.sleep(1)\nprint('done')",
    context=ctx,
    timeout=60,
)
print(run.id, run.status)
```

## Wait or cancel

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
current = machine.code_interpreter.get_run(run.id)
print(current.status)

finished = machine.code_interpreter.wait_for_run(run.id, timeout_secs=120)
print(finished.status)

# machine.code_interpreter.cancel_run(run.id)
```

## List runs

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  page = machine.code_interpreter.list_runs(status="succeeded", limit=20)
  for item in page["items"]:
      print(item.id, item.status)
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine code run-job list mch_123 --status succeeded --limit 20
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl "${NULLSPACE_API_URL}/v1/machines/mch_123/code/runs?status=succeeded&limit=20" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

## Artifacts

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  artifacts = machine.code_interpreter.list_artifacts(limit=20)
  for item in artifacts["items"]:
      print(item["id"], item.get("kind"))

  artifact = machine.code_interpreter.get_artifact("artifact_...")
  content = machine.code_interpreter.download_artifact(artifact.id)
  preview = machine.code_interpreter.preview_artifact(artifact.id)
  machine.code_interpreter.delete_artifact(artifact.id)
  ```

  ```bash CLI theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  nullspace machine code artifact list mch_123 --limit 20
  nullspace machine code artifact get mch_123 <artifact-id>
  nullspace machine code artifact download mch_123 <artifact-id> -o ./artifact.bin
  nullspace machine code artifact preview mch_123 <artifact-id> -o ./preview.bin
  nullspace machine code artifact delete mch_123 <artifact-id>
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  curl "${NULLSPACE_API_URL}/v1/machines/mch_123/code/artifacts?limit=20" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  curl "${NULLSPACE_API_URL}/v1/machines/mch_123/code/artifacts/<artifact-id>" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  curl "${NULLSPACE_API_URL}/v1/machines/mch_123/code/artifacts/<artifact-id>/download" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" -o ./artifact.bin
  curl "${NULLSPACE_API_URL}/v1/machines/mch_123/code/artifacts/<artifact-id>/preview" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" -o ./preview.bin
  curl -X DELETE "${NULLSPACE_API_URL}/v1/machines/mch_123/code/artifacts/<artifact-id>" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}"
  ```
</CodeGroup>

`list_artifacts()` returns paginated raw artifact dictionaries. Use
`get_artifact()` for a typed `CodeArtifact`, and use `download_artifact()` or
`preview_artifact()` for bytes.

## Related

* [Contexts](./contexts)
* [Streaming](./streaming)
* [API Reference](../api-reference)