> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get an agent

> Retrieve the full details of a single Agent by ID.

`GET /api/v1/cloud/agents/{agent_id}`

Returns the full details of the specified Agent.

## Headers

| Header          | Required | Description    |
| --------------- | -------- | -------------- |
| `Authorization` | Yes      | `Bearer <PAT>` |

## Path parameters

| Parameter  | Type   | Required | Description                                      |
| ---------- | ------ | -------- | ------------------------------------------------ |
| `agent_id` | string | Yes      | Agent unique identifier with the `agent_` prefix |

## Query parameters

| Parameter | Type    | Required | Description                                                                |
| --------- | ------- | -------- | -------------------------------------------------------------------------- |
| `version` | integer | No       | Return a specific Agent version snapshot. Omit to return the current Agent |

## Example request

```bash theme={null}
curl -X GET "https://api.qoder.com/api/v1/cloud/agents/agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Authorization: Bearer $QODER_PAT"
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent",
  "description": "",
  "model": "ultimate",
  "system": "You are a documentation testing assistant.",
  "tools": [],
  "mcp_servers": [],
  "skills": [
    {"type": "custom", "skill_id": "skill_019e5d133c057536872f745e0b6dbd5d"}
  ],
  "metadata": {},
  "multiagent": null,
  "version": 1,
  "archived_at": null,
  "created_at": "2026-05-18T15:26:39.61669Z",
  "updated_at": "2026-05-18T15:26:39.61669Z"
}
```

## Response fields

When `version` is omitted, the response is the current [Agent object](/cloud-agents/api/agents/schemas#agent-object). When `version` is provided, the response is an [Agent version snapshot](/cloud-agents/api/agents/schemas#agent-version-snapshot).

| Field         | Type                                                                     | Description                                                                       |
| ------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
| `type`        | string                                                                   | Always `"agent"`                                                                  |
| `id`          | string                                                                   | Agent unique identifier                                                           |
| `name`        | string                                                                   | Agent name                                                                        |
| `description` | string                                                                   | Agent description                                                                 |
| `model`       | string \| object                                                         | Model identifier. See [Agent model](/cloud-agents/api/agents/schemas#agent-model) |
| `system`      | string                                                                   | System prompt                                                                     |
| `tools`       | array of [Agent tool](/cloud-agents/api/agents/schemas#agent-tool)       | Tool configuration list                                                           |
| `mcp_servers` | array of [MCP server](/cloud-agents/api/agents/schemas#mcp-server)       | MCP server configuration                                                          |
| `skills`      | array of [Skill binding](/cloud-agents/api/agents/schemas#skill-binding) | Skill bindings                                                                    |
| `metadata`    | [Metadata object](/cloud-agents/api/conventions/schemas#metadata-object) | Custom metadata                                                                   |
| `multiagent`  | [Multiagent](/cloud-agents/api/agents/schemas#multiagent) \| null        | Agents configuration, `null` when not set                                         |
| `version`     | integer                                                                  | Current version                                                                   |
| `archived_at` | string\|null                                                             | Archive time (ISO 8601), `null` when not archived                                 |
| `created_at`  | string                                                                   | Creation time (ISO 8601)                                                          |
| `updated_at`  | string                                                                   | Last update time (ISO 8601)                                                       |

## Errors

| HTTP | Type                    | Trigger                                |
| ---- | ----------------------- | -------------------------------------- |
| 400  | `invalid_request_error` | `version` is not a positive integer    |
| 401  | `authentication_error`  | PAT invalid or expired                 |
| 403  | `permission_error`      | Not authorized for this Agent          |
| 404  | `not_found_error`       | Agent with the given ID does not exist |

See [Errors](/cloud-agents/api/conventions/errors) for the full error envelope.

### Error response example

```json theme={null}
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "not_found_error",
    "message": "Agent 'agent_nonexistent' was not found."
  }
}
```

## Related

<CardGroup cols={2}>
  <Card title="Agent setup" icon="user-gear" href="/cloud-agents/define-agent">
    Create a reusable, versioned agent configuration.
  </Card>
</CardGroup>