Invocations

An invocation is a request to execute a handler that is part of a Restate service. There are three ways to invoke a handler: over HTTP, using typed clients, or through Kafka topics.

HTTP invocations

To call a function over HTTP, send a request to the Restate Server, specifying the service and the function you want to invoke. For example, to call the processPayment function of the PaymentService:

curl -X POST localhost:8080/restate/call/PaymentService/processPayment \
--json '{"amount": 100, "currency": "USD"}'

The Restate Server ingress endpoint is here hosted at localhost:8080. To call Virtual Objects or Workflows, you need to specify the object key or workflow ID in the URL. For example, to call updateBalance of the UserAccount object with key user123:

curl -X POST localhost:8080/restate/call/UserAccount/user123/updateBalance \
--json '{"amount": 50}'

Check out the HTTP invocation docs to learn more.

Typed client invocations

Use typed clients from external applications to invoke Restate handlers:

//import * as clients from "@restatedev/restate-sdk-clients";
const restateClient = clients.connect({ url: "http://localhost:8080" });

// To call a service:
const greet = await restateClient
  .serviceClient(greeterService)
  .greet({ greeting: "Hi" });

var restate = Client.connect("http://localhost:8080");

// To call a service:
restate.service(MyService.class).myHandler(req);

async with restate.create_client("http://localhost:8080") as client:
    response = await client.service_call(my_handler, arg="Hi")

restateClient := restateingress.NewClient("http://localhost:8080")

// To call a service
response, err := restateingress.Service[*MyInput, *MyOutput](
  restateClient, "MyService", "MyHandler").
  Request(context.Background(), &input)
if err != nil {
  return err
}

For service-to-service calls within handlers, see Service Communication.

Kafka invocations

You can connect your Restate handlers to Kafka topics, to let Restate invoke them for each message. Consult the Kafka Quickstart to get started.

Idempotency

Add an idempotency key to your request header to let Restate deduplicate retries:

curl -X POST localhost:8080/restate/call/PaymentService/processPayment \
-H 'idempotency-key: payment-123' \
--json '{"amount": 100, "currency": "USD"}'

On retry, Restate returns the first invocation’s result or lets you attach to it if still running.

Flow control

Send an invocation through a scope to apply concurrency limits, capping how many invocations run at once for that scope. This helps you control cost, protect downstream services, and keep scheduling fair.

curl -X POST localhost:8080/restate/scope/checkout/call/OrderService/checkout \
--json '{"orderId": "order-123"}'

See flow control to learn how to configure concurrency limits.

Inspecting invocations

Use the Restate UI to monitor and troubleshoot invocations:

Attaching to invocations

Attach to ongoing invocations to retrieve their results:

const handle = ctx
  .serviceSendClient(myService)
  .myHandler("Hi", sendOpts({ idempotencyKey: "my-key" }));
const invocationId = await handle.invocationId;

// Later...
const response = ctx.attach(invocationId);

var handle =
    Restate.serviceHandle(MyService.class)
        .send(MyService::myHandler, "Hi", InvocationOptions.idempotencyKey("my-key"));
var response = handle.attach().await();

handle = ctx.service_send(my_handler, "Hi", idempotency_key="my-key")
invocation_id = await handle.invocation_id()

# Later...
await ctx.attach_invocation(invocation_id)

// Execute the request and retrieve the invocation id
invocationId := restate.
  ServiceSend(ctx, "MyService", "MyHandler").
  Send("Hi", restate.WithIdempotencyKey("my-idempotency-key")).
  GetInvocationId()

// Later re-attach to the request
response, err := restate.AttachInvocation[string](ctx, invocationId).Response()

Or over HTTP:

curl localhost:8080/restate/attach/inv_1234567890abcdef

This is useful when another process needs the result of an ongoing operation or wants to check whether it has completed.

Cancelling invocations

Cancel running invocations when they’re no longer needed:

restate invocations cancel inv_1234567890abcdef

curl -X PATCH http://localhost:9070/invocations/inv_1gdJBtdVEcM942bjcDmb1c1khoaJe11Hbz/cancel

Or programmatically:

const handle = ctx.serviceSendClient(myService).myHandler("Hi");
const invocationId = await handle.invocationId;

// Cancel the invocation
ctx.cancel(invocationId);

var handle = Restate.serviceHandle(MyService.class).send(MyService::myHandler, "Hi");

// Cancel the invocation
handle.cancel();

handle = ctx.service_send(my_handler, "Hi", idempotency_key="my-key")
invocation_id = await handle.invocation_id()

# Cancel the invocation
ctx.cancel_invocation(invocation_id)

// Execute the request and retrieve the invocation id
invocationId := restate.
  ServiceSend(ctx, "MyService", "MyHandler").
  Send("Hi").
  GetInvocationId()

// I don't need this invocation anymore, let me just cancel it
restate.CancelInvocation(ctx, invocationId)

To roll back the actions the handler already completed before cancellation, check out at the sagas guide.

Use Cases

Foundations

Tour of Restate for...

HTTP invocations

Typed client invocations

Kafka invocations

Idempotency

Flow control

Inspecting invocations

Attaching to invocations

Cancelling invocations

​HTTP invocations

​Typed client invocations

​Kafka invocations

​Idempotency

​Flow control

​Inspecting invocations

​Attaching to invocations

​Cancelling invocations

HTTP invocations

Typed client invocations

Kafka invocations

Idempotency

Flow control

Inspecting invocations

Attaching to invocations

Cancelling invocations