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

# get_intuned_client

> [!NOTE]
>
> This feature is in **preview**. The API may change before general availability. To try it out, contact [support@intunedhq.com](mailto:support@intunedhq.com) and we'll enable it for your workspace.

```python theme={null}
from intuned_runtime import get_intuned_client, get_async_intuned_client

def get_intuned_client(
    *,
    workspace_id: str | None = None,
    timeout: float | None = None,
    dry_run: bool | Callable[[dict[str, Any]], None] = False,
) -> IntunedClient: ...

def get_async_intuned_client(
    *,
    workspace_id: str | None = None,
    timeout: float | None = None,
    dry_run: bool | Callable[[dict[str, Any]], None] = False,
) -> AsyncIntunedClient: ...
```

Return a ready [Intuned client SDK](https://intunedhq.com/docs/client-apis/overview.md#python) client for the workspace your automation runs in: `IntunedClient` from `get_intuned_client`, `AsyncIntunedClient` from `get_async_intuned_client`. Use it to start Runs of any Project in the workspace from inside an automation and read their results, without putting an API key in your code.

Inside a Run, the client authenticates with the Run's own token and reads it again on every request, so a refreshed token is always used. Outside a Run, for example with the CLI on your machine, it uses `INTUNED_API_KEY`, or `INTUNED_AUTH_TOKEN` when there is no API key.

## Install

The helpers need `intuned-client` 1.2.0 or later. Install it with the `client` extra of the runtime:

```bash theme={null}
uv add 'intuned-runtime[client]'
```

## Parameters

**workspace\_id** `str | None`

The workspace to call. Defaults to the workspace the automation runs in.
Inside a Run, only that workspace is allowed.

**timeout** `float | None`

Request timeout in seconds.

**dry\_run** `bool | Callable[[dict[str, Any]], None]`

Print each request instead of sending it, or pass a function to receive each
request. Credentials are masked. Client methods then return `None`.
Recommended in the IDE and the local CLI.

## Returns

An `IntunedClient` (or `AsyncIntunedClient`). It has the same methods as one you create yourself, for example `client.projects.runs.start()` and `client.projects.runs.result()`. See the [Run API reference](https://intunedhq.com/docs/client-apis/api-reference/projectsruns/run-api--start.md).

## Raises

* `ImportError` when `intuned-client` isn't installed, or is older than 1.2.0, with the command to install or upgrade it.
* `RuntimeError` inside a Run, when `workspace_id` names another workspace.
* `RuntimeError` in AuthSession `create` and `check` functions. Call it from an API instead.
* `RuntimeError` when it has no credentials or can't tell which workspace to call. With the CLI, run `intuned provision` first.

## What a Run can call

Inside a Run, the client can call two operations, on any Project in the workspace:

| Operation | Method |
| - | - |
| Start a Run | `client.projects.runs.start()` |
| Get a Run result | `client.projects.runs.result()` |

Every other operation, such as canceling a Run or managing Jobs and AuthSessions, fails with `401` inside a Run. Outside a Run, the client can call everything your API key allows.

## Runs started from a Run

Inside a Run, `client.projects.runs.start()` does three things for you:

* **Links the new Run to this one.** The new Run records this Run as its parent and the first Run of the chain as its root. Run details show who started it, with links to the parent and root Runs, and the parent's Run details list it under **Child Runs**. The Run result's `metadata` has `parentRunId` and `rootRunId`.
* **Passes on this Run's attributes.** The new Run starts with this Run's current [attributes](https://intunedhq.com/docs/main/02-features/run-attributes.md), including ones set earlier in this Attempt. Attributes you pass in the request body override them by key.
* **Makes retries safe.** Without an `idempotency_key`, the client derives one from this Run's ID and the request. When an Attempt fails and the next Attempt starts the same Run again, it gets the first Run back instead of starting a second one. See [Idempotency keys](https://intunedhq.com/docs/main/02-features/runs-single-executions.md#idempotency-keys).

Because of that default key, two identical `runs.start()` calls in the same Run return the same Run. To start several Runs with the same request, give each one its own `idempotency_key`.

Inside a Run, call `runs.start()` with keyword arguments: `project_name`, `body` (a model or a dict) and, optionally, `idempotency_key`.

A chain of Runs starting Runs can be at most 10 deep. The Run at depth 10 gets a `403` if it tries to start another one.

> [!NOTE]
>
> In the IDE, Runs started this way aren't linked as child Runs and get no
> default idempotency key.

## Example

Start a Run in another Project, wait for it, and return its result:

```python theme={null}
import asyncio

from intuned_runtime import get_async_intuned_client


async def automation(page, params, **_kwargs):
    async with get_async_intuned_client() as client:
        started = await client.projects.runs.start(
            project_name="product-details",
            body={"api": "get-product", "parameters": {"ids": params["product_ids"]}},
        )

        while True:
            run = await client.projects.runs.result(
                project_name="product-details", run_id=started.run_id
            )
            if run.status == "completed":
                return run.result
            if run.status in ("failed", "canceled"):
                raise RuntimeError(f"Run {started.run_id} ended as {run.status}")
            await asyncio.sleep(5)
```

To start the same request more than once in one Run, pass a key per Run. Keep the keys stable across Attempts so a retried Attempt still gets the same Runs back:

```python theme={null}
from intuned_runtime import get_async_intuned_client, run_info


async def automation(page, params, **_kwargs):
    async with get_async_intuned_client() as client:
        for i in range(3):
            await client.projects.runs.start(
                project_name="pricing",
                body={"api": "list-prices", "parameters": {"region": "us"}},
                idempotency_key=f"{run_info().run_id}-pricing-{i}",
            )
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.