통화 목록

할 수 있는 일

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

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 상담사 연결을 기다려요. 번호 전환 중에는 `inProgress`예요
`completed`	통화가 완료됐어요
`noAnswer`	상대가 받지 않아 끝났어요
`failed`	발신 또는 통화가 실패했어요. 통화 중 응답도 여기에 포함돼요
`cancelled`	취소돼 끝났어요

queued·ringing·busy 같은 값은 목록의 status 필터로 받지 않아요. 통화 중 응답은 failed와 endReason: "dial_busy"로 구분해요. 자세한 판정은 통화 상세를 보세요.

날짜·시간 필터

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

URL에 직접 넣는 예

createdAfter=2026-10-20T09:00:00%2B09:00

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

기간과 대상으로 조회

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의 각 항목은 통화 상세와 같은 통화 객체예요.

200 예시

{
  "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이면 마지막 페이지예요.

다음 페이지 조회

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>는 앞선 응답의 실제 값으로 바꾸세요.

생성 결과를 모를 때

통화 생성에서 502 call_outcome_unknown을 받으면 대상과 생성 시각으로 목록을 확인하세요. 목록에는 상대 전화번호가 포함되지 않아요. 목록이 비었다는 응답 한 번만으로 미발신을 단정하거나, 확인 없이 새 멱등 키로 재발신하지 마세요.

오류

HTTP	코드	대처
`400`	`invalid_query`	쿼리 타입·범위·상태·날짜 형식과 `+` 인코딩을 확인하세요
`400`	`invalid_cursor`	이 API 응답의 `nextCursor`를 수정 없이 사용하세요
`401`	`unauthenticated`	인증을 확인하세요

그 밖의 오류는 REST 오류를 보세요.

개요

REST API

SDK

MCP

업무 데이터

A2A

할 수 있는 일

쿼리

상태 필터

날짜·시간 필터

결과

다음 페이지

생성 결과를 모를 때

오류

관련 문서

​할 수 있는 일

​쿼리

​상태 필터

​날짜·시간 필터

​결과

​다음 페이지

​생성 결과를 모를 때

​오류

​관련 문서

할 수 있는 일

쿼리

상태 필터

날짜·시간 필터

결과

다음 페이지

생성 결과를 모를 때

오류

관련 문서