# Get a Genie run

> Returns the state of a run started with Run a Genie and, once the Genie has answered, its latest reply. Pass the region the run answer carried: the conversation is read from that data region. While the Genie works, status is processing and there is no result; completed carries the reply in result and its id in message_id; failed means the run could not finish.

Source: https://docs.stacksync.com/api-reference/genies/runs/get_genie_run

`GET https://genies.stacksync.com/v1/workspaces/{workspace_id}/genies/run/{conversation_id}`

- Operation: `get_genie_run`
- Resource: Genie runs
- Access: read-only

## Authentication

- `Authorization: Bearer <key>`: A workspace API key (workspace_…, created by a workspace owner under Workspace settings > Stacksync API) acts with editor rights on that workspace only; a user API key (user_…, created under Profile > Stacksync API) acts as that user in every workspace they belong to. POST requests must send Content-Type: application/json. Every authentication failure answers 403. Running a Genie needs the editor role in the workspace.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace_id` | integer | Yes | The workspace whose Genie runs. A workspace API key works only on its own workspace; a user API key on any workspace the user belongs to. |
| `conversation_id` | string (uuid) | Yes | The conversation_id the run answer carried. |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `region` | string (besg \| usnv) | No | Data region of the resources: the region the run answer carried. Allowed values: besg, usnv. Defaults to the region of the server that answers, so always pass it. |

## Returns

### 200 The run's current state. A conversation not yet stored answers processing.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `status` | string (processing \| completed \| failed) | Yes | processing: the Genie is still working (or the message steered a run in progress). completed: the Genie answered; result holds the reply. failed: the run could not finish. |
| `conversation_id` | string (uuid) \| null | Yes | The conversation of the run. Send it back to continue the conversation. |
| `region` | string (besg \| usnv \| null) | Yes | Data region the conversation is stored in. Null only on a failure answered before the region was resolved. |
| `message_id` | string (uuid) \| null | Yes | Id of the Genie's latest reply in the conversation; null while there is none. |
| `result` | string | No | The text of the Genie's latest reply. Present once the conversation holds a reply. |
| `widget` | object | No | The structured action the reply proposes, when the Genie attached one to its reply. |
| `options` | object (GenieReplyOptions) | No | Details attached to the reply. Carries approval when the Genie paused on an action that needs an approval; decide it with the approval decision operation using the same API key. |
| `options.approval` | object (GenieApproval) | No | An action the Genie is waiting to have approved before it runs it. |
| `options.approval.approval_id` | string (uuid) | Yes | Id of the approval, used to decide it. |
| `options.approval.type` | string (execute_module) | Yes | What kind of action waits: execute_module, a connector action. |
| `options.approval.region` | string (besg \| usnv) | Yes | Data region the approval is stored in. Allowed values: besg, usnv. |
| `options.approval.instructions` | string | Yes | What the Genie intends to do with the action. |
| `options.approval.status` | string (awaiting_approval \| rejected \| approved_once \| approved_always \| unknown_outcome) | Yes | State of the approval. awaiting_approval until it is decided. |
| `options.approval.decision_at` | string (date-time) \| null | Yes | When the approval was decided, ISO 8601 UTC without offset; null while it waits. |
| `options.approval.module_id` | string | No | Id of the connector action waiting for approval. |
| `options.approval.module_name` | string | No | Name of the connector action waiting for approval. |
| `options.approval.connection_id` | string \| null | No | Id of the connection the action would use. |
| `options.approval.connection_name` | string \| null | No | Name of the connection the action would use. |
| `options.approval_delivery` | object | No | Where the approval request was delivered when the run asked for an external delivery. |
| `attachments` | array of object (GenieReplyAttachment) | No | The files the reply produced, as stored file references. Present once the conversation holds a reply; empty when the reply has no file. |
| `attachments[].file_id` | string | Yes | Id of the stored file. |
| `attachments[].filename` | string | Yes | Name of the file. |
| `attachments[].content_type` | string | Yes | Media type of the file, such as application/pdf. |
| `error` | string | No | Why the run failed, when it stopped before the Genie answered or the region is unknown. |

## Example request

```bash
curl -X GET "https://genies.stacksync.com/v1/workspaces/{workspace_id}/genies/run/{conversation_id}?region=usnv" \
  -H "Authorization: Bearer $STACKSYNC_API_KEY"
```

## Example response (200)

```json
{
  "status": "completed",
  "conversation_id": "14d0a0ba-9352-44d6-a7f7-8fd2c3ce0388",
  "region": "usnv",
  "message_id": "346f36a0-1902-4871-87d1-11f2d5433d9b",
  "result": "Hello, world! I am the Hello World API Demo genie.",
  "attachments": [],
  "options": {}
}
```

## Errors

| Status | Meaning | Body |
| --- | --- | --- |
| 400 | The region is not a Stacksync data region. The body is a failed run envelope whose error names the region. | `{ "status": string (processing \| completed \| failed), "conversation_id": string (uuid) \| null, "region": string (besg \| usnv \| null), "message_id": string (uuid) \| null, "result": string, "widget": object, "options": object (GenieReplyOptions), "attachments": array of object (GenieReplyAttachment), "error": string }` |
| 403 | The caller is not allowed: Authorization Error (header missing or not Bearer), Invalid API Key (unknown key, key of another workspace, or a user who is not a member of the workspace), Content-Type Error (POST without application/json), Insufficient Scope (a read-only sign-in on a request that changes data) or Authentication Error (your role in the workspace is below editor). | `{ "error": string, "msg": string, "field": string }` |

## Related

- [API Reference overview](https://docs.stacksync.com/api-reference): base URLs, regions, pagination, idempotency and errors
- [Authentication](https://docs.stacksync.com/api-reference/authentication): API keys and the 403 answers
- OpenAPI document: https://docs.stacksync.com/openapi-genies.json
- [Run a Genie](https://docs.stacksync.com/api-reference/genies/runs/run_genie)
- [Run a Genie and wait for the result](https://docs.stacksync.com/api-reference/genies/runs/run_genie_and_wait)