---
title: "## Datacenter Round Trips"
method: PUT
path: "/actors"
tags: ["actors::get_or_create"]
---

# ## Datacenter Round Trips

`PUT /actors`

**If actor exists**

2 round trips:
- namespace::ops::resolve_for_name_global
- GET /actors/{}

**If actor does not exist and is created in the current datacenter:**

2 round trips:
- namespace::ops::resolve_for_name_global
- [pegboard::workflows::actor] Create actor workflow (includes Epoxy key allocation)

**If actor does not exist and is created in a different datacenter:**

3 round trips:
- namespace::ops::resolve_for_name_global
- POST /actors to remote datacenter
- [pegboard::workflows::actor] Create actor workflow (includes Epoxy key allocation)

actor::get will always be in the same datacenter.

## Optimized Alternative Routes

## Query parameters

- `namespace` string, required

## Request body

- ActorsGetOrCreateRequest
  - `crash_policy` 'restart' | 'sleep' | 'destroy', required
  - `datacenter` string, nullable
  - `input` string, nullable
  - `key` string, required
  - `name` string, required
  - `runner_name_selector` string, required

## Response `200`

- ActorsGetOrCreateResponse
  - `actor` Actor, required
    - `actor_id` string, required
    - `connectable_ts` integer, nullable — Denotes when the actor was last connectable. Null if actor is not running.
    - `crash_policy` 'restart' | 'sleep' | 'destroy', required
    - `create_ts` integer, required — Denotes when the actor was first created.
    - `datacenter` string, required
    - `destroy_ts` integer, nullable — Denotes when the actor was destroyed.
    - `error` object, nullable — Error details if the actor failed to start.
    - `key` string, nullable
    - `name` string, required
    - `namespace_id` string, required
    - `pending_allocation_ts` integer, nullable — Denotes when the actor started waiting for an allocation.
    - `reschedule_ts` integer, nullable — Denotes when the actor will try to allocate again. If this is set, the actor will not attempt to allocate until the given timestamp.
    - `runner_name_selector` string, required
    - `sleep_ts` integer, nullable — Denotes when the actor entered a sleeping state.
    - `start_ts` integer, nullable — Denotes when the actor was first made connectable. Null if never.
  - `created` boolean, required

---

[API](https://skmtc.net/rivet-dev/apis/rivet-api-public.md) · [All operations](https://skmtc.net/rivet-dev/apis/rivet-api-public/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/rivet-dev/rivet-api-public/versions/a22e2e3f6322/schema)