Skip to main content
An invocation is a request to execute a handler. Each invocation has its own unique ID and lifecycle.
Conversation State Management

​
Invocation ID

Invocations have a unique Invocation ID starting with inv_. You can find this ID in every place where an invocation is mentioned:
  • The invocations page of the Restate UI
  • Logs and traces (restate.invocation.id), both in Restate and SDKs
  • In CLI commands such as restate invocation ls

​
Lifecycle

Invocations follow a well-defined lifecycle: Invocation lifecycle This page describes how to manage invocations in different states.

​
Cancel

You can cancel an invocation at any point in its lifecycle. Cancellation has the following characteristics:
  • Frees held resources
  • Cooperates with your handler code to roll back any changes made so far
  • Allows proper cleanup
restate invocations cancel inv_1gdJBtdVEcM942bjcDmb1c1khoaJe11Hbz

# Or bulk cancel, e.g. per service or handler
restate invocations cancel Greeter
restate invocations cancel Greeter/greet
restate invocations cancel CartObject/cart55/add
Cancellation is non-blocking. The API call may return before cancellation completes. In rare cases, cancellation may not take effect - retry the operation if needed.
For proper rollback, handlers must include compensation logic to maintain service state consistency. Check the sagas guide.

​
Requirements

For cancellation to work, the invocation must reach the deployment (the service endpoint must be reachable).If the deployment is not reachable, use kill instead.

​
Cancellation Flow

When an invocation is canceled:
  1. User sends cancellation request to the Restate runtime
  2. Runtime forwards cancellation to the SDK eagerly
  3. SDK surfaces cancellation at the next await point in your handler code
The cancellation exception (TerminalError in TypeScript/Python, TerminalException in Java/Kotlin) is thrown at the next await point - operations that wait for a result, such as ctx.run(), call responses, sleeps, awakeable results, etc.
One-way calls (ctx.send()) and delayed calls (ctx.sendDelayed()) are detached from the call tree. They will be scheduled and execute fully even if the originating invocation is cancelled.

​
Example

async function processOrder(ctx: restate.ObjectContext, order: Order) {
  // If cancellation happened before this line, this still executes
  ctx.set("status", "processing");

  // If cancellation happened before this line, this still executes
  const paymentId = ctx.rand.uuidv4().toString();

  try {
    // If cancelled right before this line, ctx.run won't execute
    // If cancelled during run block execution,
    // then a terminal error gets thrown here once execution finishes
    await ctx.run(() => processPayment(paymentId, order));

    // If cancellation happened before this line, this still executes
    ctx.serviceSendClient(notificationService).notify("Payment processed");

  } catch (error) {
    if (error instanceof restate.TerminalError) {
      // Cancellation detected - run compensation
      await ctx.run(() => refundPayment(paymentId, order));
      throw error; // Re-throw to propagate cancellation
    }
  }
}

​
Call Graph Propagation

Cancellation propagates recursively through the call graph:
  1. Propagate to leaves: Cancellation first reaches the leaves of the call graph
  2. Throw at await points: Each handler receives the cancellation exception at its next await point
  3. Run compensation: Handlers execute their compensation logic (if defined)
  4. Propagate upward: Cancellation flows back up the call graph (unless handled differently), allowing each parent to compensate

​
Kill

Use kill when cancellation fails (e.g., when endpoints are permanently unavailable). Killing immediately stops all calls in the invocation tree without executing compensation logic. This may leave your service in an inconsistent state. Only use as a last resort after trying other fixes. Note that one-way calls and delayed calls are not killed because they’re detached from the originating call tree. 
restate invocations kill inv_1gdJBtdVEcM942bjcDmb1c1khoaJe11Hbz

# Or bulk kill, e.g. per service
restate invocations kill Greeter
restate invocations kill Greeter/greet
restate invocations kill CartObject/cart55/add

​
Resume

If an invocation retries for too many times, Restate will pause it. When an invocation is paused, you need to resume it manually: 
restate invocations resume inv_1gdJBtdVEcM942bjcDmb1c1khoaJe11Hbz

# Or bulk resume, e.g. per service
restate invocations resume Greeter
Check out the service configuration docs to tune the invocation retry policy, including the retry interval and how many attempts to perform before pausing. You can also resume an invocation that is waiting on a retry timer, instructing Restate to retry immediately.
When resuming, the invocation will run on the same deployment where it started.If the invocation failed due to some bug you fixed on a new/different deployment, you can override on which deployment the invocation should be resumed:
curl -X PATCH http://localhost:9070/invocations/inv_1gdJBtdVEcM942bjcDmb1c1khoaJe11Hbz/resume\?deployment=dp_17sztQp4gnEC1L0OCFM9aEh
Be aware that if the business logic/flow between the old and the new deployment code differ, once resumed the invocation will start fail with non-determinism errors!

​
Purge

After an invocation completes, it will be retained by Restate for some time, in order to introspect it and, in case of idempotent requests, to perform deduplication. Check out the service configuration docs to tune the retention time. You can also manually purge completed invocations if you need to free up disk space: 
restate invocations purge inv_1gdJBtdVEcM942bjcDmb1c1khoaJe11Hbz

# Or bulk purge, e.g. per service
restate invocations purge Greeter

​
Restart as new

Invocations, once completed, can be restarted as new invocations: 
restate invocations restart-as-new inv_1gdJBtdVEcM942bjcDmb1c1khoaJe11Hbz

# Or bulk restart as new, e.g. per service
restate invocations restart-as-new Greeter
The new invocation will have a different invocation ID, but the input and headers of the original request. The old invocation will be left untouched. Keep in mind that when restarting an invocation as new, no partial progress will be kept, meaning all the operations the service executed will be executed again. This feature is not available for workflows.