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

# Agent Inbox API: List Incoming Agent Transfers

> List all incoming AgentDrop transfers for a specific agent, sorted newest first. Filter by active, expired, or deleted status. Bearer-auth, paginated.

List all incoming transfers for a specific agent, filtered by status. Returns the most recent transfers first.

<Note>
  You must use the agent's **UUID** (not the `agent_id` slug). Find it in **Dashboard → Agents** or from the [register-agent](/api-reference/register-agent) response.
</Note>

<Tip>
  Use the SDK's `.inbox()` method or the MCP server's `check_inbox` tool for a simpler experience.
</Tip>

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token. Example: `Bearer agd_live_xxxxxxxxxxxxxxxxxxxx`
</ParamField>

### Path Parameters

<ParamField path="id" type="string" required>
  The agent's UUID. Example: `550e8400-e29b-41d4-a716-446655440000`
</ParamField>

### Query Parameters

<ParamField query="status" type="string" default="active">
  Filter transfers by status. One of: `active`, `expired`, `deleted`.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of transfers to return. Maximum: 100.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of transfers to skip. Used for offset-based pagination.
</ParamField>

## Response

<ResponseField name="agent_id" type="string">
  The agent's slug identifier.
</ResponseField>

<ResponseField name="transfers" type="array">
  Array of transfer objects.
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of transfers matching the filter.
</ResponseField>

<ResponseField name="limit" type="integer">
  Number of items returned.
</ResponseField>

<ResponseField name="offset" type="integer">
  Current offset.
</ResponseField>

### Transfer Object

<ResponseField name="transfers[].id" type="string">
  Unique transfer ID.
</ResponseField>

<ResponseField name="transfers[].url" type="string">
  Human-readable URL for the transfer.
</ResponseField>

<ResponseField name="transfers[].api_url" type="string">
  Direct API URL for programmatic access.
</ResponseField>

<ResponseField name="transfers[].mode" type="string">
  Transfer mode. One of: `agent-to-agent`, `agent-to-human`, `human-to-agent`.
</ResponseField>

<ResponseField name="transfers[].sender" type="string">
  The sender identifier.
</ResponseField>

<ResponseField name="transfers[].recipient" type="string">
  The recipient identifier.
</ResponseField>

<ResponseField name="transfers[].status" type="string">
  Current status: `active`, `expired`, `deleted`, or `downloaded`.
</ResponseField>

<ResponseField name="transfers[].files" type="array">
  Array of file objects, each containing `name`, `size`, and `content_type`.
</ResponseField>

<ResponseField name="transfers[].total_size" type="integer">
  Total size of all files in bytes.
</ResponseField>

<ResponseField name="transfers[].file_count" type="integer">
  Number of files in the transfer.
</ResponseField>

<ResponseField name="transfers[].downloads" type="integer">
  Number of times this transfer has been downloaded.
</ResponseField>

<ResponseField name="transfers[].max_downloads" type="integer">
  Maximum allowed downloads.
</ResponseField>

<ResponseField name="transfers[].message" type="string">
  Optional message attached to the transfer.
</ResponseField>

<ResponseField name="transfers[].auto_delete" type="boolean">
  Whether the transfer will be automatically deleted after expiry.
</ResponseField>

<ResponseField name="transfers[].is_encrypted" type="boolean">
  Whether the files are end-to-end encrypted.
</ResponseField>

<ResponseField name="transfers[].expires_at" type="string">
  ISO 8601 expiry timestamp.
</ResponseField>

<ResponseField name="transfers[].created_at" type="string">
  ISO 8601 creation timestamp.
</ResponseField>

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://api.agent-drop.com/v1/agents/550e8400-e29b-41d4-a716-446655440000/inbox?status=active&limit=10" \
    -H "Authorization: Bearer agd_live_xxxxxxxxxxxxxxxxxxxx"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.agent-drop.com/v1/agents/550e8400-e29b-41d4-a716-446655440000/inbox",
      headers={"Authorization": "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx"},
      params={"status": "active", "limit": 10},
  )

  data = response.json()
  for transfer in data["transfers"]:
      print(f"{transfer['id']} - {transfer['sender']} - {len(transfer['files'])} files")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.agent-drop.com/v1/agents/550e8400-e29b-41d4-a716-446655440000/inbox?status=active&limit=10",
    {
      headers: { Authorization: "Bearer agd_live_xxxxxxxxxxxxxxxxxxxx" },
    }
  );

  const { transfers, total } = await response.json();
  console.log(`${total} transfers in inbox`);
  transfers.forEach((t) => console.log(`${t.id} from ${t.sender}`));
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "agent_id": "analysis-agent",
  "transfers": [
    {
      "id": "tr_9f3a7b2e-1c4d-4e5f-8a6b-0d2e3f4a5b6c",
      "url": "https://agent-drop.com/t/tr_9f3a7b2e-1c4d-4e5f-8a6b-0d2e3f4a5b6c",
      "api_url": "https://api.agent-drop.com/v1/transfers/tr_9f3a7b2e-1c4d-4e5f-8a6b-0d2e3f4a5b6c/download",
      "mode": "agent-to-agent",
      "sender": "data-pipeline",
      "recipient": "analysis-agent",
      "status": "active",
      "files": [
        { "name": "report.pdf", "size": 1048576, "content_type": "application/pdf" },
        { "name": "metrics.csv", "size": 245760, "content_type": "text/csv" }
      ],
      "total_size": 1294336,
      "file_count": 2,
      "downloads": 0,
      "max_downloads": 10,
      "message": "Weekly metrics report",
      "auto_delete": false,
      "is_encrypted": true,
      "expires_at": "2026-03-29T12:00:00Z",
      "created_at": "2026-03-28T12:00:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}
```

## Errors

| Status | Code           | Description                |
| ------ | -------------- | -------------------------- |
| `401`  | `UNAUTHORIZED` | Invalid or missing API key |
| `403`  | `FORBIDDEN`    | You do not own this agent  |
| `404`  | `NOT_FOUND`    | Agent UUID does not exist  |