Actors API reference

Dapr provides native, cross-platform, and cross-language virtual actor capabilities. Besides the language specific SDKs, a developer can invoke an actor using the API endpoints below.

User service code calling Dapr

Invoke actor method

Invoke an actor method through Dapr.

HTTP Request

POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/method/<method>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

Example of invoking a method on an actor:

curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/method/shoot \
  -H "Content-Type: application/json"

You can provide the method parameters and values in the body of the request, for example in curl using -d "{\"param\":\"value\"}". Example of invoking a method on an actor that takes parameters:

curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
  -H "Content-Type: application/json" \
  -d '{
        "destination": "Hoth"
      }'

or

curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
  -H "Content-Type: application/json" \
  -d "{\"destination\":\"Hoth\"}"

The response (the method return) from the remote endpoint is returned in the request body.

Actor state transactions

Persists the change to the state for an actor as a multi-item transaction.

Note that this operation is dependant on a using state store component that supports multi-item transactions.

TTL

With the ActorStateTTL feature enabled, actor clients can set the ttlInSeconds field in the transaction metadata to have the state expire after that many seconds. If the ttlInSeconds field is not set, the state will not expire.

Keep in mind when building actor applications with this feature enabled; Currently, all actor SDKs will preserve the actor state in their local cache even after the state has expired. This means that the actor state will not be removed from the local cache if the TTL has expired until the actor is restarted or deactivated. This behaviour will be changed in a future release.

See the Dapr Community Call 80 recording for more details on actor state TTL.

HTTP Request

POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

Note, the following example uses the ttlInSeconds field, which requires the ActorStateTTL feature enabled.

curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state \
  -H "Content-Type: application/json" \
  -d '[
       {
         "operation": "upsert",
         "request": {
           "key": "key1",
           "value": "myData",
           "metadata": {
             "ttlInSeconds": "3600"
           }
         }
       },
       {
         "operation": "delete",
         "request": {
           "key": "key2"
         }
       }
      ]'

Get actor state

Gets the state for an actor using a specified key.

HTTP Request

GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state/<key>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
  -H "Content-Type: application/json"

The above command returns the state:

{
  "location": "Alderaan"
}

Create actor reminder

Creates a persistent reminder for an actor.

HTTP Request

POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>

Reminder request body

A JSON object with the following fields:

period field supports time.Duration format and ISO 8601 format with some limitations. For period, only duration format of ISO 8601 duration Rn/PnYnMnWnDTnHnMnS is supported. Rn/ specifies that the reminder will be invoked n number of times.

• n should be a positive integer greater than 0.
• If certain values are 0, the period can be shortened; for example, 10 seconds can be specified in ISO 8601 duration as PT10S.

If Rn/ is not specified, the reminder will run an infinite number of times until deleted.

If only ttl and dueTime are set, the reminder will be accepted. However, only the dueTime takes effect. For example, the reminder triggers at dueTime, and ttl is ignored.

If ttl, dueTime, and period are set, the reminder first fires at dueTime, then repeatedly fires and expires according to period and ttl.

The following example specifies a dueTime of 3 seconds and a period of 7 seconds.

{
  "dueTime":"0h0m3s0ms",
  "period":"0h0m7s0ms"
}

A dueTime of 0 means to fire immediately. The following body means to fire immediately, then every 9 seconds.

{
  "dueTime":"0h0m0s0ms",
  "period":"0h0m9s0ms"
}

To configure the reminder to fire only once, the period should be set to empty string. The following specifies a dueTime of 3 seconds with a period of empty string, which means the reminder will fire in 3 seconds and then never fire again.

{
  "dueTime":"0h0m3s0ms",
  "period":""
}

When you specify the repetition number in both period and ttl, the timer/reminder is stopped when either condition is met. The following example has a timer with a period of 3 seconds (in ISO 8601 duration format) and a ttl of 20 seconds. This timer fires immediately after registration, then every 3 seconds after that for the duration of 20 seconds, after which it never fires again since the ttl was met

{
  "period":"PT3S",
  "ttl":"20s"
}

Need description for data.

{
  "data": "someData",
  "dueTime": "1m",
  "period": "20s"
}

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
  -H "Content-Type: application/json" \
-d '{
      "data": "someData",
      "dueTime": "1m",
      "period": "20s"
    }'

Get actor reminder

Gets a reminder for an actor.

HTTP Request

GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
  "Content-Type: application/json"

The above command returns the reminder:

{
  "dueTime": "1s",
  "period": "5s",
  "data": "0",
}

Delete actor reminder

Deletes a reminder for an actor.

HTTP Request

DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/reminders/<name>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

curl -X DELETE http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
  -H "Content-Type: application/json"

Create actor timer

Creates a timer for an actor.

HTTP Request

POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>

Timer request body:

The format for the timer request body is the same as for actor reminders. For example:

The following specifies a dueTime of 3 seconds and a period of 7 seconds.

{
  "dueTime":"0h0m3s0ms",
  "period":"0h0m7s0ms"
}

A dueTime of 0 means to fire immediately. The following body means to fire immediately, then every 9 seconds.

{
  "dueTime":"0h0m0s0ms",
  "period":"0h0m9s0ms"
}

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
    -H "Content-Type: application/json" \
-d '{
      "data": "someData",
      "dueTime": "1m",
      "period": "20s",
      "callback": "myEventHandler"
    }'

Delete actor timer

Deletes a timer for an actor.

HTTP Request

DELETE http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers/<name>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

curl -X DELETE http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
  -H "Content-Type: application/json"

Dapr calling to user service code

Get registered actors

Get the registered actors types for this app and the Dapr actor configuration settings.

HTTP Request

GET http://localhost:<appPort>/dapr/config

HTTP Response Codes

URL Parameters

Examples

Example of getting the registered actors:

curl -X GET http://localhost:3000/dapr/config \
  -H "Content-Type: application/json"

The above command returns the config (all fields are optional):

{
  "entities":["actorType1", "actorType2"],
  "actorIdleTimeout": "1h",
  "actorScanInterval": "30s",
  "drainOngoingCallTimeout": "30s",
  "drainRebalancedActors": true,
  "reentrancy": {
    "enabled": true,
    "maxStackDepth": 32
  },
  "entitiesConfig": [
      {
          "entities": ["actorType1"],
          "actorIdleTimeout": "1m",
          "drainOngoingCallTimeout": "10s",
          "reentrancy": {
              "enabled": false
          }
      }
  ]
}

Deactivate actor

Deactivates an actor by persisting the instance of the actor to the state store with the specified actorId.

HTTP Request

DELETE http://localhost:<appPort>/actors/<actorType>/<actorId>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

The following example deactivates the actor type stormtrooper that has actorId of 50.

curl -X DELETE http://localhost:3000/actors/stormtrooper/50 \
  -H "Content-Type: application/json"

Invoke actor method

Invokes a method for an actor with the specified methodName where:

• Parameters to the method are passed in the body of the request message.
• Return values are provided in the body of the response message.

If the actor is not already running, the app side should activate it.

HTTP Request

PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/<methodName>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

The following example calls the performAction method on the actor type stormtrooper that has actorId of 50.

curl -X POST http://localhost:3000/actors/stormtrooper/50/method/performAction \
  -H "Content-Type: application/json"

Invoke reminder

Invokes a reminder for an actor with the specified reminderName. If the actor is not already running, the app side should activate it.

HTTP Request

PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/remind/<reminderName>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

The following example calls the checkRebels reminder method on the actor type stormtrooper that has actorId of 50.

curl -X POST http://localhost:3000/actors/stormtrooper/50/method/remind/checkRebels \
  -H "Content-Type: application/json"

Invoke timer

Invokes a timer for an actor with the specified timerName. If the actor is not already running, the app side should activate it.

HTTP Request

PUT http://localhost:<appPort>/actors/<actorType>/<actorId>/method/timer/<timerName>

HTTP Response Codes

URL Parameters

Note, all URL parameters are case-sensitive.

Examples

The following example calls the checkRebels timer method on the actor type stormtrooper that has actorId of 50.

curl -X POST http://localhost:3000/actors/stormtrooper/50/method/timer/checkRebels \
  -H "Content-Type: application/json"

Health check

Probes the application for a response to signal to Dapr that the app is healthy and running. Any response status code other than 200 will be considered an unhealthy response.

A response body is not required.

HTTP Request

GET http://localhost:<appPort>/healthz

HTTP Response Codes

URL Parameters

Examples

Example of getting a health check response from the app:

curl -X GET http://localhost:3000/healthz \

SubscribeActorEventsAlpha1 (gRPC)

SubscribeActorEventsAlpha1 is a bidirectional gRPC streaming RPC on the Dapr service (dapr.proto.runtime.v1.Dapr). The application is the gRPC client: it dials daprd, opens the stream, and receives all actor callbacks — method invocations, reminders, timers, and deactivations — over that single connection. Apps using this RPC do not need to expose an HTTP or gRPC server port.

See the actor app-initiated streams concept doc and how-to guide for usage guidance and code examples.

gRPC service definition

// On the Dapr service (app dials daprd):
rpc SubscribeActorEventsAlpha1(stream SubscribeActorEventsRequestAlpha1)
    returns (stream SubscribeActorEventsResponseAlpha1) {}

App → Dapr: SubscribeActorEventsRequestAlpha1

Messages sent from the app to daprd. The first message must be initial_request; all subsequent messages must be responses correlated by id.

SubscribeActorEventsRequestInitialAlpha1

SubscribeActorEventsRequestInvokeResponseAlpha1

SubscribeActorEventsRequestReminderResponseAlpha1

Used for both reminder_response and timer_response.

SubscribeActorEventsRequestDeactivateResponseAlpha1

SubscribeActorEventsRequestFailedAlpha1

Dapr → App: SubscribeActorEventsResponseAlpha1

Messages sent from daprd to the app. The first message is initial_response; all subsequent messages are callback requests.

SubscribeActorEventsResponseInvokeRequestAlpha1

SubscribeActorEventsResponseReminderRequestAlpha1

SubscribeActorEventsResponseTimerRequestAlpha1

SubscribeActorEventsResponseDeactivateRequestAlpha1

Activating an Actor

Conceptually, activating an actor means creating the actor’s object and adding the actor to a tracking table. Review an example from the .NET SDK.

Querying actor state externally

To enable visibility into the state of an actor and allow for complex scenarios like state aggregation, Dapr saves actor state in external state stores, such as databases. As such, it is possible to query for an actor state externally by composing the correct key or query.

The state namespace created by Dapr for actors is composed of the following items:

• App ID: Represents the unique ID given to the Dapr application.
• Actor Type: Represents the type of the actor.
• Actor ID: Represents the unique ID of the actor instance for an actor type.
• Key: A key for the specific state value. An actor ID can hold multiple state keys.

The following example shows how to construct a key for the state of an actor instance under the myapp App ID namespace:

myapp||cat||hobbit||food

In the example above, we are getting the value for the state key food, for the actor ID hobbit with an actor type of cat, under the App ID namespace of myapp.