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

# 통화 목록

> 계정의 통화를 상태·대상·생성 시각으로 거르고, 커서로 다음 페이지를 조회해요.

## 할 수 있는 일

인증한 계정의 원 통화 목록을 조회해요. REST로 만든 통화뿐 아니라 다른 연동 방식의 통화도
포함해요. **전환으로 파생된 별도 통화와 포털 테스트 통화는 제외**해요.

```http theme={null}
GET https://api.telloai.io/v1/calls
```

## 쿼리

모든 쿼리는 선택이고, 같은 이름을 여러 번 보내지 마세요.

| 이름 | 타입 · 기본값 | 설명 |
| - | - | - |
| `limit` | 정수 · `20` | 페이지 크기. `1`\~`100`이에요 |
| `cursor` | 문자열 · 없음 | 이전 응답의 `nextCursor`를 그대로 보내요 |
| `status` | 문자열 · 없음 | 공개 상태 7개 중 하나예요 |
| `agentId` | 숫자 문자열 · 없음 | 이 에이전트의 통화만 조회해요 |
| `crewId` | 숫자 문자열 · 없음 | 이 크루의 통화만 조회해요 |
| `createdAfter` | ISO-8601 날짜 또는 시간대가 있는 시각 · 없음 | `createdAt`이 이 시각 **이상**인 통화를 조회해요 |
| `createdBefore` | ISO-8601 날짜 또는 시간대가 있는 시각 · 없음 | `createdAt`이 이 시각 **미만**인 통화를 조회해요 |

조건은 함께 적용돼요. `agentId`와 `crewId`를 같이 보내면 두 조건을 모두 만족하는 통화만
조회해요. 생성 요청에서 둘 중 하나만 고르는 규칙과 달리, 여기서는 조회 필터예요.

### 상태 필터

| `status` | 의미 |
| - | - |
| `dialing` | 발신을 준비하거나 상대의 응답을 기다려요 |
| `inProgress` | 통화가 연결돼 진행 중이에요 |
| `transferring` | [상담APP](https://docs.telloai.io/channels/agent-app.md) 상담사 연결을 기다려요. [번호 전환](https://docs.telloai.io/developer/rest/transfer-call.md) 중에는 `inProgress`예요 |
| `completed` | 통화가 완료됐어요 |
| `noAnswer` | 상대가 받지 않아 끝났어요 |
| `failed` | 발신 또는 통화가 실패했어요. 통화 중 응답도 여기에 포함돼요 |
| `cancelled` | 취소돼 끝났어요 |

`queued`·`ringing`·`busy` 같은 값은 목록의 `status` 필터로 받지 않아요.
통화 중 응답은 `failed`와 `endReason: "dial_busy"`로 구분해요. 자세한 판정은
[통화 상세](https://docs.telloai.io/developer/rest/get-call.md)를 보세요.

### 날짜·시간 필터

* `2026-10-20`처럼 날짜만 보내면 **UTC 자정**으로 해석해요.
* 시각을 보낼 때는 `Z`나 `+09:00`처럼 시간대를 밝혀야 해요. 시간대가 없는
  `2026-10-20T09:00:00`은 `400 invalid_query`예요.
* UTC로 변환한 연도가 `1`\~`9999`여야 해요.
* URL 쿼리에서 `+`는 공백으로 해석돼요. 오프셋의 `+`를 **`%2B`로 인코딩**하세요.

```text URL에 직접 넣는 예 theme={null}
createdAfter=2026-10-20T09:00:00%2B09:00
```

`curl --data-urlencode`를 쓰면 인코딩을 직접 하지 않아도 돼요. 다음 예시는 한국 시각
10월 20일 하루를 조회해요. `createdAfter`는 포함하고 `createdBefore`는 제외하므로,
다음 날 자정의 통화는 포함되지 않아요.

```bash 기간과 대상으로 조회 theme={null}
curl --get "https://api.telloai.io/v1/calls" \
  --header "Authorization: Bearer <API_KEY>" \
  --data-urlencode "limit=20" \
  --data-urlencode "agentId=12" \
  --data-urlencode "createdAfter=2026-10-20T00:00:00+09:00" \
  --data-urlencode "createdBefore=2026-10-21T00:00:00+09:00"
```

## 결과

성공하면 \*\*`200 OK`\*\*와 `{ data, nextCursor }`가 와요. `data`의 각 항목은
[통화 상세](https://docs.telloai.io/developer/rest/get-call.md)와 같은 통화 객체예요.

```json 200 예시 theme={null}
{
  "data": [
    {
      "id": "c_12345",
      "status": "completed",
      "direction": "outbound",
      "source": "api",
      "agentId": "12",
      "crewId": null,
      "createdAt": "2026-10-20T01:00:00.000Z",
      "startedAt": "2026-10-20T01:00:08.000Z",
      "endedAt": "2026-10-20T01:01:08.000Z",
      "durationSeconds": 60,
      "endReason": null,
      "transcript": null,
      "summary": null,
      "creditCharged": null
    }
  ],
  "nextCursor": null
}
```

정렬은 **`createdAt` 내림차순**, 같은 시각이면 **통화 id의 숫자 부분 내림차순**이에요.
조건에 맞는 통화가 없으면 `data`는 빈 배열이고 `nextCursor`는 `null`이에요.

### 다음 페이지

`nextCursor`가 문자열이면 다음 페이지가 있어요. 그 값을 그대로 `cursor`에 넣고, 나머지
조회 조건은 유지하세요. 커서의 내용을 해석하거나 직접 만들거나 수정하지 마세요.
`nextCursor`가 `null`이면 마지막 페이지예요.

```bash 다음 페이지 조회 theme={null}
curl --get "https://api.telloai.io/v1/calls" \
  --header "Authorization: Bearer <API_KEY>" \
  --data-urlencode "limit=20" \
  --data-urlencode "agentId=12" \
  --data-urlencode "createdAfter=2026-10-20T00:00:00+09:00" \
  --data-urlencode "createdBefore=2026-10-21T00:00:00+09:00" \
  --data-urlencode "cursor=<NEXT_CURSOR>"
```

`<NEXT_CURSOR>`는 앞선 응답의 실제 값으로 바꾸세요.

## 생성 결과를 모를 때

[통화 생성](https://docs.telloai.io/developer/rest/create-call.md)에서 `502 call_outcome_unknown`을 받으면 대상과
생성 시각으로 목록을 확인하세요. 목록에는 상대 전화번호가 포함되지 않아요. 목록이 비었다는
응답 한 번만으로 미발신을 단정하거나, 확인 없이 새 멱등 키로 재발신하지 마세요.

## 오류

| HTTP | 코드 | 대처 |
| - | - | - |
| `400` | `invalid_query` | 쿼리 타입·범위·상태·날짜 형식과 `+` 인코딩을 확인하세요 |
| `400` | `invalid_cursor` | 이 API 응답의 `nextCursor`를 수정 없이 사용하세요 |
| `401` | `unauthenticated` | [인증](https://docs.telloai.io/developer/rest/overview.md#인증)을 확인하세요 |

그 밖의 오류는 [REST 오류](https://docs.telloai.io/developer/rest/errors.md)를 보세요.

## 관련 문서

* [통화 생성](https://docs.telloai.io/developer/rest/create-call.md)
* [통화 상세](https://docs.telloai.io/developer/rest/get-call.md)
* [통화 종료](https://docs.telloai.io/developer/rest/end-call.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.