# `Gemini.APIs.Operations`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/operations.ex#L1)

Operations API for managing long-running operations.

Long-running operations are returned by asynchronous API calls that may take
significant time to complete, such as:

- Video generation
- File imports
- Model tuning
- Large batch processing

## Polling Pattern

The typical pattern for handling long-running operations:

    # Start a long-running operation
    {:ok, operation} = some_async_api_call()

    # Wait for completion with polling
    {:ok, completed} = Gemini.APIs.Operations.wait(operation.name,
      poll_interval: 5000,      # Check every 5 seconds
      timeout: 600_000,         # Wait up to 10 minutes
      on_progress: fn op ->
        if progress = Gemini.Types.Operation.get_progress(op) do
          IO.puts("Progress: #{progress}%")
        end
      end
    )

    # Handle result
    if Gemini.Types.Operation.succeeded?(completed) do
      result = completed.response
      # Process successful result
    else
      error = completed.error
      # Handle error
    end

## Manual Polling

For more control, you can poll manually:

    {:ok, op} = Gemini.APIs.Operations.get(operation_name)

    cond do
      Operation.succeeded?(op) -> handle_success(op.response)
      Operation.failed?(op) -> handle_failure(op.error)
      Operation.running?(op) -> poll_again_later()
    end

## Cancellation

Some operations can be cancelled while in progress:

    :ok = Gemini.APIs.Operations.cancel(operation_name)

# `list_opts`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/operations.ex#L74)

```elixir
@type list_opts() :: [
  page_size: pos_integer(),
  page_token: String.t(),
  filter: String.t(),
  auth: :gemini | :vertex_ai
]
```

# `operation_opts`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/operations.ex#L65)

```elixir
@type operation_opts() :: [{:auth, :gemini | :vertex_ai}]
```

# `wait_opts`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/operations.ex#L67)

```elixir
@type wait_opts() :: [
  poll_interval: pos_integer(),
  timeout: pos_integer(),
  on_progress: (Gemini.Types.Operation.t() -> any()),
  auth: :gemini | :vertex_ai
]
```

# `cancel`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/operations.ex#L179)

```elixir
@spec cancel(String.t(), operation_opts()) :: :ok | {:error, term()}
```

Cancel a running operation.

Not all operations support cancellation. If the operation doesn't support
cancellation or is already complete, this may return an error.

## Parameters

- `name` - Operation name
- `opts` - Options

## Examples

    :ok = Gemini.APIs.Operations.cancel("operations/abc123")

# `delete`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/operations.ex#L203)

```elixir
@spec delete(String.t(), operation_opts()) :: :ok | {:error, term()}
```

Delete an operation.

Typically used to clean up completed operations.

## Parameters

- `name` - Operation name
- `opts` - Options

## Examples

    :ok = Gemini.APIs.Operations.delete("operations/abc123")

# `get`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/operations.ex#L100)

```elixir
@spec get(String.t(), operation_opts()) ::
  {:ok, Gemini.Types.Operation.t()} | {:error, term()}
```

Get the current status of an operation.

## Parameters

- `name` - Operation name (e.g., "operations/abc123")
- `opts` - Options

## Examples

    {:ok, op} = Gemini.APIs.Operations.get("operations/abc123")

    if op.done do
      IO.puts("Operation completed")
    else
      IO.puts("Still running...")
    end

# `list`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/operations.ex#L135)

```elixir
@spec list(list_opts()) ::
  {:ok, Gemini.Types.ListOperationsResponse.t()} | {:error, term()}
```

List operations, optionally filtered.

## Parameters

- `opts` - List options

## Options

- `:page_size` - Number of operations per page (default: 100)
- `:page_token` - Token from previous response for pagination
- `:filter` - Filter string (e.g., "done=true")
- `:auth` - Authentication strategy

## Examples

    # List all operations
    {:ok, response} = Gemini.APIs.Operations.list()

    # List only completed operations
    {:ok, response} = Gemini.APIs.Operations.list(filter: "done=true")

    # With pagination
    {:ok, response} = Gemini.APIs.Operations.list(page_size: 10)

# `list_all`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/operations.ex#L159)

```elixir
@spec list_all(list_opts()) :: {:ok, [Gemini.Types.Operation.t()]} | {:error, term()}
```

List all operations across all pages.

Automatically handles pagination to retrieve all operations.

## Parameters

- `opts` - List options

## Examples

    {:ok, all_ops} = Gemini.APIs.Operations.list_all()
    completed = Enum.filter(all_ops, &Operation.complete?/1)

# `wait`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/operations.ex#L260)

```elixir
@spec wait(String.t(), wait_opts()) ::
  {:ok, Gemini.Types.Operation.t()} | {:error, term()}
```

Wait for an operation to complete.

Polls the operation status until it reaches a terminal state (done = true),
or the timeout is reached.

## Parameters

- `name` - Operation name
- `opts` - Wait options

## Options

- `:poll_interval` - Milliseconds between status checks (default: 5000)
- `:timeout` - Maximum wait time in milliseconds (default: 600000 = 10 min)
- `:on_progress` - Callback for status updates `fn(Operation.t()) -> any()`

## Returns

- `{:ok, Operation.t()}` - Completed operation (check `done`, `error`, `response`)
- `{:error, :timeout}` - Timed out waiting for completion
- `{:error, reason}` - Failed to poll status

## Examples

    # Simple wait
    {:ok, completed} = Gemini.APIs.Operations.wait("operations/abc123")

    # With progress tracking
    {:ok, completed} = Gemini.APIs.Operations.wait("operations/abc123",
      poll_interval: 2000,
      timeout: 300_000,
      on_progress: fn op ->
        if progress = Operation.get_progress(op) do
          IO.puts("Progress: #{progress}%")
        end
      end
    )

    # Handle result
    cond do
      Operation.succeeded?(completed) ->
        IO.puts("Success: #{inspect(completed.response)}")
      Operation.failed?(completed) ->
        IO.puts("Failed: #{completed.error.message}")
    end

# `wait_with_backoff`
[🔗](https://github.com/nshkrdotcom/gemini_ex/blob/v0.11.0/lib/gemini/apis/operations.ex#L298)

```elixir
@spec wait_with_backoff(
  String.t(),
  keyword()
) :: {:ok, Gemini.Types.Operation.t()} | {:error, term()}
```

Wait for an operation with exponential backoff.

Similar to `wait/2` but uses exponential backoff for polling intervals,
which is more efficient for operations that may take a long time.

## Parameters

- `name` - Operation name
- `opts` - Wait options

## Options

Same as `wait/2` plus:
- `:initial_delay` - Initial delay in milliseconds (default: 1000)
- `:max_delay` - Maximum delay in milliseconds (default: 30000)
- `:multiplier` - Backoff multiplier (default: 2)

## Examples

    {:ok, completed} = Gemini.APIs.Operations.wait_with_backoff("operations/abc123",
      initial_delay: 1000,
      max_delay: 30_000,
      timeout: 600_000
    )

---

*Consult [api-reference.md](api-reference.md) for complete listing*