---
sidebar:
  hidden: true
title: roboto.domain.actions.invocation
---
## Module Contents

### Invocation

```python
class roboto.domain.actions.invocation.Invocation(
    record: roboto.domain.actions.invocation_record.InvocationRecord,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
)
```

`from roboto import Invocation`

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/actions/invocation.py#L50-L507)

An instance of an execution of an action, initiated manually by a user or automatically by a trigger.

An Invocation represents a single execution of an Action with specific inputs, parameters, and configuration. It tracks the execution lifecycle from creation through completion, including status updates, logs, and results.

Invocations are created by calling [`Action.invoke()`](/reference/python-sdk/roboto/domain/actions/action#roboto.domain.actions.action.Action.invoke) or through the UI. They cannot be created directly through the constructor. Each invocation has a unique ID and maintains a complete audit trail of its execution.

Key features:

- Status tracking (Queued, Running, Completed, Failed, etc.)
- Input data specification and parameter values
- Compute requirement and container parameter overrides
- Log collection and output file management
- Progress monitoring and result retrieval

**Parameters**

- **record** (`roboto.domain.actions.invocation_record.InvocationRecord`)
- **roboto_client** (`Optional[roboto.http.RobotoClient]`)

**Properties**

- **Invocation.action** (`roboto.domain.actions.invocation_record.ActionProvenance`): Provenance information about the action that was invoked.

- **Invocation.compute_requirements** (`roboto.domain.actions.action_record.ComputeRequirements`): The compute requirements (CPU, memory) used for this invocation.

- **Invocation.container_parameters** (`roboto.domain.actions.action_record.ContainerParameters`): The container parameters used for this invocation.

- **Invocation.created** (`datetime.datetime`): The timestamp when this invocation was created.

- **Invocation.current_status** (`roboto.domain.actions.invocation_record.InvocationStatus`): The current status of this invocation (e.g., Queued, Running, Completed).

- **Invocation.data_source** (`roboto.domain.actions.invocation_record.InvocationDataSource`): The data source that provided input data for this invocation.

- **Invocation.executable** (`roboto.domain.actions.invocation_record.ExecutableProvenance`): Provenance information about the executable (container) that was run.

- **Invocation.id** (`str`): The unique identifier for this invocation.

- **Invocation.input_data** (`roboto.domain.actions.invocation_record.InvocationInput | None`): The input data specification for this invocation, if any.

  Return type: `Optional[roboto.domain.actions.invocation_record.InvocationInput]`

- **Invocation.org_id** (`str`): The organization ID that owns this invocation.

- **Invocation.parameter_values** (`dict[str, Any]`): The parameter values that were provided when this invocation was created.

- **Invocation.reached_terminal_status** (`bool`): True if this invocation has reached a terminal status (Completed, Failed, etc.).

- **Invocation.record** (`roboto.domain.actions.invocation_record.InvocationRecord`): The underlying invocation record containing all invocation data.

- **Invocation.source** (`roboto.domain.actions.invocation_record.SourceProvenance`): Provenance information about the source that initiated this invocation.

- **Invocation.status_log** (`list[roboto.domain.actions.invocation_record.InvocationStatusRecord]`): The complete history of status changes for this invocation.

- **Invocation.timeout** (`int`): The timeout in minutes for this invocation.

- **Invocation.upload_destination** (`roboto.domain.actions.invocation_record.InvocationUploadDestination | None`): The destination where output files from this invocation will be uploaded.

  Return type: `Optional[roboto.domain.actions.invocation_record.InvocationUploadDestination]`

#### Invocation.cancel()

```python
def cancel() -> None
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/actions/invocation.py#L322-L346)

Cancel this invocation if it is not already in a terminal status.

Attempts to cancel the invocation. If the invocation has already completed, failed, or reached another terminal status, this method has no effect.

**Raises**

- [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException): If the invocation is not found.
- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): If the caller lacks permission to cancel the invocation.

**Returns**

- `None`

**Usage**

Cancel a running invocation:

```python
invocation = Invocation.from_id("iv_12345")
if not invocation.reached_terminal_status:
    invocation.cancel()
```

#### Invocation.from_id()

```python
@classmethod
def from_id(
    invocation_id: str,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
) -> Invocation
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/actions/invocation.py#L74-L104)

Load an existing invocation by its ID.

Retrieves an invocation from the Roboto platform using its unique identifier.

**Parameters**

- **invocation_id** (`str`): The unique ID of the invocation to retrieve.
- **roboto_client** (`Optional[roboto.http.RobotoClient]`): Roboto client instance. Uses default if not provided.

**Returns**

- `Invocation`: The Invocation instance.

**Raises**

- [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException): If the invocation is not found.
- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): If the caller lacks permission to access the invocation.

**Usage**

Load an invocation and check its status:

```python
invocation = Invocation.from_id("iv_12345")
print(f"Status: {invocation.current_status}")
print(f"Created: {invocation.created}")
```

#### Invocation.get_logs()

```python
def get_logs(
    page_token: Optional[str] = None,
) -> collections.abc.Generator[roboto.domain.actions.invocation_record.LogRecord, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/actions/invocation.py#L348-L377)

Retrieve runtime STDOUT/STDERR logs generated during this invocation's execution.

Fetches log records from the invocation's container execution, with support for pagination to handle large log volumes.

**Parameters**

- **page_token** (`Optional[str]`): Optional token for pagination. If provided, starts retrieving logs from that point.

**Yields**

- LogRecord instances containing log messages and metadata.

**Raises**

- [`RobotoNotFoundException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoNotFoundException): If the invocation is not found.
- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): If the caller lacks permission to access logs.

**Returns**

- `collections.abc.Generator[roboto.domain.actions.invocation_record.LogRecord, None, None]`

#### Invocation.is_queued_for_scheduling()

```python
def is_queued_for_scheduling() -> bool
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/actions/invocation.py#L379-L388)

**An invocation is queued for scheduling if:**

1\. its most recent status is "Queued" 3. and is not "Deadly"

**Returns**

- `bool`

#### Invocation.query()

```python
@classmethod
def query(
    spec: Optional[roboto.query.QuerySpecification] = None,
    owner_org_id: Optional[str] = None,
    roboto_client: Optional[roboto.http.RobotoClient] = None,
) -> collections.abc.Generator[Invocation, None, None]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/actions/invocation.py#L107-L204)

Query invocations with optional filtering and pagination.

Searches for invocations based on the provided query specification. Can filter by status, action name, creation time, and other attributes.

**Parameters**

- **spec** (`Optional[roboto.query.QuerySpecification]`): Query specification with filters, sorting, and pagination. If not provided, returns all accessible invocations.
- **owner_org_id** (`Optional[str]`): Organization ID to search within. If not provided, searches in the caller's organization.
- **roboto_client** (`Optional[roboto.http.RobotoClient]`): Roboto client instance. Uses default if not provided.

**Yields**

- Invocation instances matching the query criteria.

**Raises**

- `ValueError`: If the query specification contains unknown fields.
- [`RobotoIllegalArgumentException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoIllegalArgumentException): If the query filters or sorts on a field the invocations API does not accept.
- [`RobotoUnauthorizedException`](/reference/python-sdk/roboto/exceptions/domain#roboto.exceptions.domain.RobotoUnauthorizedException): If the caller lacks permission to query invocations.

**Returns**

- `collections.abc.Generator[Invocation, None, None]`

**Usage**

Query all invocations:

```python
for invocation in Invocation.query():
    print(f"Invocation: {invocation.id}")
```

Query invocations whose data source is a given dataset:

```python
from roboto.query import Comparator, Condition, QuerySpecification
spec = QuerySpecification(
    condition=Condition(
        field="data_source_id",
        comparator=Comparator.Equals,
        value="ds_abc123",
    )
)
for invocation in Invocation.query(spec):
    print(invocation.id)
```

Query completed invocations:

```python
from roboto.domain.actions import InvocationStatus
spec = QuerySpecification(
    condition=Condition(
        field="last_status",
        comparator=Comparator.Equals,
        value=InvocationStatus.Completed.value,
    )
)
completed = list(Invocation.query(spec))
```

Query the ten most recent invocations. Neither `limit` nor `max_results` caps an invocation query, so take the first ten from the generator:

```python
import itertools
from roboto.query import SortDirection
spec = QuerySpecification(sort_by="created", sort_direction=SortDirection.Descending)
recent = list(itertools.islice(Invocation.query(spec), 10))
```

#### Invocation.refresh()

```python
def refresh() -> Invocation
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/actions/invocation.py#L390-L392)

**Returns**

- `Invocation`

#### Invocation.set_container_image_digest()

```python
def set_container_image_digest(digest: str) -> Invocation
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/actions/invocation.py#L394-L410)

This is an admin-only operation to memorialize the digest of the container image that was pulled in the course of invoking the action.

**Parameters**

- **digest** (`str`)

**Returns**

- `Invocation`

#### Invocation.set_logs_location()

```python
def set_logs_location(
    logs: roboto.domain.actions.invocation_record.LogsLocation,
) -> Invocation
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/actions/invocation.py#L412-L426)

This is an admin-only operation to memorialize the base location where invocation logs are saved.

Use the "get_logs" or "stream_logs" methods to access invocation logs.

**Parameters**

- **logs** (`roboto.domain.actions.invocation_record.LogsLocation`)

**Returns**

- `Invocation`

#### Invocation.stream_logs()

```python
def stream_logs(
    last_read: Optional[str] = None,
) -> collections.abc.Generator[roboto.domain.actions.invocation_record.LogRecord, None, Optional[str]]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/actions/invocation.py#L428-L452)

**Parameters**

- **last_read** (`Optional[str]`)

**Returns**

- `collections.abc.Generator[roboto.domain.actions.invocation_record.LogRecord, None, Optional[str]]`

#### Invocation.to_dict()

```python
def to_dict() -> dict[str, Any]
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/actions/invocation.py#L454-L455)

**Returns**

- `dict[str, Any]`

#### Invocation.update_status()

```python
def update_status(
    next_status: roboto.domain.actions.invocation_record.InvocationStatus,
    detail: Optional[str] = None,
) -> Invocation
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/actions/invocation.py#L457-L481)

**Parameters**

- **next_status** (`roboto.domain.actions.invocation_record.InvocationStatus`)
- **detail** (`Optional[str]`)

**Returns**

- `Invocation`

#### Invocation.wait_for_terminal_status()

```python
def wait_for_terminal_status(
    timeout: float = 60 * 5,
    poll_interval: roboto.waiters.Interval = 5,
) -> None
```

[Source](https://github.com/roboto-ai/roboto-python-sdk/blob/main/src/roboto/domain/actions/invocation.py#L483-L507)

Wait for the invocation to reach a terminal status.

Throws a [`TimeoutError`](/reference/python-sdk/roboto/waiters#roboto.waiters.TimeoutError) if the timeout is reached.

**Parameters**

- **timeout** (`float`): The maximum amount of time, in seconds, to wait for the invocation to reach a terminal status.
- **poll_interval** (`roboto.waiters.Interval`): The amount of time, in seconds, to wait between polling iterations.

**Returns**

- `None`