Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,26 @@ The following request body configures a timer with a `dueTime` of 10 seconds, a
}
```

### Retrieve actor timer

You can retrieve a single timer registered for an actor by calling

```md
GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>
```

### List actor timers

You can list all the timers registered for an actor by calling

```md
GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers
```

Timers are kept in memory by the sidecar that hosts the actor and are not persisted. Both requests must therefore be sent to the sidecar that currently owns the actor. A sidecar that hosts the actor type but does not own this actor returns `403` with `ERR_ACTOR_TIMER_NOT_OWNED`; a sidecar that does not host the actor type returns `403` with `ERR_ACTOR_TIMER_NON_HOSTED`. Timers whose `ttl` had already elapsed at registration are never stored and are not returned. The gRPC equivalents are `GetActorTimer` and `ListActorTimers`.

### Remove the actor timer

You can remove the actor timer by calling

```md
Expand Down Expand Up @@ -153,6 +173,16 @@ You can retrieve the actor reminder by calling
GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
```

### List actor reminders

You can list all the reminders registered for an actor by calling

```md
GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders
```

The gRPC equivalent, `ListActorReminders`, also accepts a request without an actor ID to list the reminders of every actor of a given type.

### Remove the actor reminder

You can remove the actor reminder by calling
Expand Down Expand Up @@ -280,7 +310,7 @@ dapr scheduler import -f reminders-backup.bin
#### Summary

- Reminders are stored in the Dapr Scheduler, not in the app.
- Create reminders via the Actors API
- Create, get, list, and delete reminders via the Actors API.
- Manage existing reminders (list, get, delete, backup/restore) using the `dapr scheduler` CLI.

## Next steps
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,11 @@ An effort is underway to enrich all gRPC error responses according to the [Riche
| `ERR_ACTOR_REMINDER_GET` | | Error getting actor reminder |
| `ERR_ACTOR_REMINDER_NON_HOSTED` | | Reminder operation on non-hosted actor type |
| `ERR_ACTOR_TIMER_CREATE` | | Error creating actor timer |
| `ERR_ACTOR_TIMER_GET` | | Error getting actor timer |
| `ERR_ACTOR_TIMER_LIST` | | Error listing actor timers |
| `ERR_ACTOR_TIMER_NOT_FOUND` | | Actor timer not found |
| `ERR_ACTOR_TIMER_NON_HOSTED` | | Timer operation on non-hosted actor type |
| `ERR_ACTOR_TIMER_NOT_OWNED` | | Timer operation on an actor not owned by this host |
| `ERR_ACTOR_NO_APP_CHANNEL` | | App channel not initialized |
| `ERR_ACTOR_STACK_DEPTH` | | Maximum actor call stack depth exceeded |
| `ERR_ACTOR_NO_PLACEMENT` | | Placement service not configured |
Expand Down
303 changes: 303 additions & 0 deletions daprdocs/content/en/reference/api/actors_api.md
Original file line number Diff line number Diff line change
Expand Up @@ -339,6 +339,117 @@ The above command returns the reminder:
}
```

### List actor reminders

Lists all the reminders registered for an actor.

#### HTTP Request

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

#### HTTP Response Codes

Code | Description
---- | -----------
200 | Request successful
403 | Actor type not hosted by this app
500 | Request failed

#### URL Parameters

Parameter | Description
--------- | -----------
`daprPort` | The Dapr port.
`actorType` | The actor type.
`actorId` | The actor ID.

> Note, all URL parameters are case-sensitive.

#### Response body

A JSON object with a `reminders` array. Each entry has the following fields; optional fields are omitted when they are not set on the reminder.

| Field | Description |
|-------|-------------|
| `name` | The name of the reminder. |
| `actorType` | The actor type. |
| `actorID` | The actor ID. |
| `dueTime` | The `dueTime` the reminder was registered with. |
| `period` | The period between invocations, in the form reported by the Scheduler, for example `@every 20s`. |
| `ttl` | The time at which the reminder expires, as an RFC3339 timestamp. |
| `data` | The `data` the reminder was registered with, returned as it was provided. |

When the actor has no reminders, `reminders` is an empty array.

#### Examples

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

The above command returns the reminders registered for the actor:

```json
{
"reminders": [
{
"name": "checkRebels",
"actorType": "stormtrooper",
"actorID": "50",
"dueTime": "1m",
"period": "@every 20s",
"data": "someData"
},
{
"name": "patrol",
"actorType": "stormtrooper",
"actorID": "50",
"dueTime": "2h",
"ttl": "2026-12-31T23:59:59Z",
"data": {
"sector": 7
}
}
]
}
```

#### gRPC

The gRPC equivalent is `dapr.proto.runtime.v1.Dapr/ListActorReminders`.

```proto
rpc ListActorReminders(ListActorRemindersRequest) returns (ListActorRemindersResponse) {}

message ListActorRemindersRequest {
string actor_type = 1;
optional string actor_id = 2;
}

message ListActorRemindersResponse {
repeated NamedActorReminder reminders = 1;
}

message NamedActorReminder {
string name = 1;
ActorReminder reminder = 2;
}

message ActorReminder {
string actor_type = 1;
string actor_id = 2;
optional string due_time = 4;
optional string period = 5;
google.protobuf.Any data = 6;
optional string ttl = 7;
}
```

Unlike the HTTP endpoint, `actor_id` is optional in the gRPC request: omit it to list the reminders of every actor of the given type. Over gRPC, `data` is a `google.protobuf.Any` wrapping a `google.protobuf.BytesValue` that contains the JSON-encoded payload the reminder was registered with.

### Delete actor reminder

Deletes a reminder for an actor.
Expand Down Expand Up @@ -437,6 +548,198 @@ curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
}'
```

### Get actor timer

Gets a timer registered for an actor.

{{% alert title="Note" color="primary" %}}
Timers are not persisted: they live in memory on the sidecar that hosts the actor. Get and list requests must be sent to that sidecar. A sidecar that hosts the actor type but does not currently own the actor rejects the request with a `403` and the `ERR_ACTOR_TIMER_NOT_OWNED` error code; a sidecar that does not host the actor type returns `403` with `ERR_ACTOR_TIMER_NON_HOSTED`. Timers whose `ttl` had already elapsed at registration are never stored and are not returned.
{{% /alert %}}

#### HTTP Request

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

#### HTTP Response Codes

Code | Description
---- | -----------
200 | Request successful
403 | Actor type not hosted by this app, or actor not owned by this sidecar
404 | Timer not found
500 | Request failed

#### URL Parameters

Parameter | Description
--------- | -----------
`daprPort` | The Dapr port.
`actorType` | The actor type.
`actorId` | The actor ID.
`name` | The name of the timer to get.

> Note, all URL parameters are case-sensitive.

#### Response body

A JSON object with the following fields; optional fields are omitted when they are not set on the timer.

| Field | Description |
|-------|-------------|
| `actorType` | The actor type. |
| `actorID` | The actor ID. |
| `dueTime` | The `dueTime` the timer was registered with. |
| `period` | The period between invocations, in the same form used for reminders, for example `@every 20s`. |
| `ttl` | The time at which the timer expires, as an RFC3339 timestamp. |
| `callback` | The `callback` the timer was registered with. |
| `data` | The `data` the timer was registered with, returned as it was provided. |

#### Examples

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

The above command returns the timer:

```json
{
"actorType": "stormtrooper",
"actorID": "50",
"dueTime": "1m",
"period": "@every 20s",
"callback": "myEventHandler",
"data": "someData"
}
```

#### gRPC

The gRPC equivalent is `dapr.proto.runtime.v1.Dapr/GetActorTimer`.

```proto
rpc GetActorTimer(GetActorTimerRequest) returns (GetActorTimerResponse) {}

message GetActorTimerRequest {
string actor_type = 1;
string actor_id = 2;
string name = 3;
}

message GetActorTimerResponse {
string actor_type = 1;
string actor_id = 2;
optional string due_time = 3;
optional string period = 4;
optional string ttl = 5;
optional string callback = 6;
google.protobuf.Any data = 7;
}
```

A request for a timer that does not exist fails with `NOT_FOUND`. A request sent to a sidecar that does not host the actor type, or does not own the actor, fails with `PERMISSION_DENIED`. Over gRPC, `data` is a `google.protobuf.Any` wrapping a `google.protobuf.BytesValue` that contains the JSON-encoded payload the timer was registered with.

### List actor timers

Lists all the timers registered for an actor. The same ownership rules as [Get actor timer]({{% ref "#get-actor-timer" %}}) apply: the request must target the sidecar that currently hosts the actor.

#### HTTP Request

```
GET http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/timers
```

#### HTTP Response Codes

Code | Description
---- | -----------
200 | Request successful
403 | Actor type not hosted by this app, or actor not owned by this sidecar
500 | Request failed

#### URL Parameters

Parameter | Description
--------- | -----------
`daprPort` | The Dapr port.
`actorType` | The actor type.
`actorId` | The actor ID.

> Note, all URL parameters are case-sensitive.

#### Response body

A JSON object with a `timers` array. Each entry has the same fields as the [Get actor timer]({{% ref "#get-actor-timer" %}}) response, plus a `name` field with the name of the timer. When the actor has no timers, `timers` is an empty array.

#### Examples

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

The above command returns the timers registered for the actor:

```json
{
"timers": [
{
"name": "checkRebels",
"actorType": "stormtrooper",
"actorID": "50",
"dueTime": "1m",
"period": "@every 20s",
"callback": "myEventHandler",
"data": "someData"
},
{
"name": "recharge",
"actorType": "stormtrooper",
"actorID": "50",
"dueTime": "30s",
"ttl": "2026-12-31T23:59:59Z"
}
]
}
```

#### gRPC

The gRPC equivalent is `dapr.proto.runtime.v1.Dapr/ListActorTimers`.

```proto
rpc ListActorTimers(ListActorTimersRequest) returns (ListActorTimersResponse) {}

message ListActorTimersRequest {
string actor_type = 1;
string actor_id = 2;
}

message ListActorTimersResponse {
repeated NamedActorTimer timers = 1;
}

message NamedActorTimer {
string name = 1;
ActorTimer timer = 2;
}

message ActorTimer {
string actor_type = 1;
string actor_id = 2;
optional string due_time = 3;
optional string period = 4;
optional string ttl = 5;
optional string callback = 6;
google.protobuf.Any data = 7;
}
```

A request sent to a sidecar that does not host the actor type, or does not own the actor, fails with `PERMISSION_DENIED`.

### Delete actor timer

Deletes a timer for an actor.
Expand Down
Loading