# See what is waiting for a person

Source: https://docs.vlayers.ai/reference/conversations/get-needs-you

`GET /v1/inbox/needs-you` · scope `messages:read`

Everything that needs someone on your team, oldest first: an agent that asked for a person (`offered`, with its reason and summary), a conversation a person has that the customer is still waiting on (`waiting_for_human`), a message held back from the agent (`held`, with why), and a message that could not be delivered (`delivery_failed`, with its code). It is read from the conversation records, so nothing is lost if it is read late.

Requires an API key with the `messages:read` scope.

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `kind` | query | "offered" \| "waiting_for_human" \| "held" \| "delivery_failed" \| "take_call" \| "follow_up" \| "question" | no | Only this kind of item: `offered`, `waiting_for_human`, `held`, `delivery_failed`, `take_call` (a call waiting for a person) or `follow_up` (a callback a caller asked for). Example: `"offered"` |
| `channel` | query | string | no | Only this channel. Example: `"sms"` |
| `lineId` | query | string | no | Only this line. Example: `"0192f5a8-1a2b-7c3d-8e4f-5a6b7c8d9e01"` |
| `assignedTo` | query | string | no | Only what is assigned to this user. Example: `"user_2abc"` |
| `conversationId` | query | string | no | Only this conversation (its ask, if it has one). Example: `"0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21"` |
| `limit` | query | integer | no | At most this many items (1-100). Example: `"25"` |

## Request

cURL:

```bash
curl "https://api.vlayers.ai/v1/inbox/needs-you?kind=offered&limit=20" \
  -H "Authorization: Bearer $VOICELAYER_API_KEY"
```

TypeScript:

```ts
import { VoiceLayer } from '@voicelayer/api';

const voicelayer = new VoiceLayer();

const { summary } = await voicelayer.conversations.getNeedsYou({ kind: 'offered', limit: 20 });
console.log(summary);
```

Python:

```python
from voicelayer import VoiceLayer

vl = VoiceLayer()

result = vl.conversations.get_needs_you(kind="offered", limit=20)
print(result.summary)
```

## Response `200`

```json
{
  "items": [
    {
      "kind": "offered",
      "conversationId": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",
      "channel": "sms",
      "lineId": "0192f5a8-1a2b-7c3d-8e4f-5a6b7c8d9e01",
      "peer": "+15550123",
      "since": "2026-10-20T15:04:05.000Z",
      "waitedSeconds": 140,
      "assignedTo": null,
      "reason": "Wants a refund over the limit",
      "summary": "Order 7, 400 dollars, damaged on arrival",
      "holdReason": null,
      "heldId": null,
      "code": null,
      "messageId": null
    }
  ],
  "counts": {
    "offered": 1,
    "waiting_for_human": 0,
    "held": 0,
    "delivery_failed": 0,
    "take_call": 0,
    "follow_up": 0,
    "question": 0
  },
  "summary": "1 conversation is waiting for a person to join."
}
```
