# Read one of an agent's connections, or the sign-in that makes it.

`GET /o/{org}/agents/{agent}/connections/{connection}`

The id a create returned reads as the sign-in while it is open (`pending`, or `failed` with an `error`), then as the connection it made, under that connection's own `id`.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org` | path | string | yes | The org's slug or id. A caller with no role in the org gets `404`. |
| `agent` | path | string | yes | The id or name of an agent made from a template (`POST /o/{org}/agents {template, name}`). |
| `connection` | path | string | yes | The id the create returned, or a connection's own id from the list. |

## Example request

```bash
curl "https://api.phoenix.so/o/$RUSH_ORG/agents/$AGENT/connections/$CONNECTION" \
  -H "Authorization: Bearer $RUSH_TOKEN"
```

```typescript
const org = process.env.RUSH_ORG;
const agent = process.env.AGENT;
const connection = process.env.CONNECTION;

const res = await fetch(`https://api.phoenix.so/o/${org}/agents/${agent}/connections/${connection}`, {
  headers: {
    Authorization: `Bearer ${process.env.RUSH_TOKEN}`,
  },
});

console.log(res.status, await res.json());
```

```python
import os

import requests

org = os.environ["RUSH_ORG"]
agent = os.environ["AGENT"]
connection = os.environ["CONNECTION"]

res = requests.get(
    f"https://api.phoenix.so/o/{org}/agents/{agent}/connections/{connection}",
    headers={"Authorization": f"Bearer {os.environ['RUSH_TOKEN']}"},
)

print(res.status_code, res.json())
```

## Responses

### 200

The connection or its sign-in.

- `id` (string, required)
- `type` (string, required, one of `app`, `mcp`)
- `name` (string, optional): The name a session's `connections` and the template use.
- `agent` (string, required): The agent the connection belongs to.
- `url` (string, optional): The MCP server's address.
- `auth` (object, optional)
  - `mode` (string, optional, one of `oauth`, `bearer`, `none`)
- `status` (string, required, one of `pending`, `connected`, `failed`)
- `authorize_url` (string, optional): Where the agent's user signs in. Single use; expires in 10 minutes.
- `error` (object, optional)
  - `code` (string, optional, one of `connection_expired`, `cancelled_by_caller`, `connection_failed`)
  - `message` (string, optional)
- `tools` (array of object, optional)
  - `name` (string, optional)
  - `title` (string, optional)
  - `description` (string, optional)
  - `read_only` (boolean, optional)

### 401

No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.

### 404

No such agent, or no such connection of it (`NOT_FOUND`).

### 429

The account is over its request budget, 1,800 a minute shared by the person's API keys and console on every API host (`RATE_LIMITED`). The error names the limit. Wait `Retry-After` seconds.

## Example response (200)

```json
{
  "id": "5a8c2e14-6b3d-4f90-9e27-d1f4a0b8c763",
  "type": "mcp",
  "name": "notion",
  "agent": "9b2f6c18-4e7a-4d35-8c91-5f0a3e7d2b66",
  "url": "https://mcp.notion.com/mcp",
  "auth": {
    "mode": "oauth"
  },
  "status": "connected",
  "tools": [
    {
      "name": "notion-search",
      "title": "Search Notion",
      "description": "Search the workspace and connected sources.",
      "read_only": true
    },
    {
      "name": "notion-create-pages",
      "title": "Create pages",
      "description": "Create one or more pages with properties and content.",
      "read_only": false
    }
  ]
}
```
