한도와 데이터
Private Beta의 기본 한도입니다. Beta 동안 값이 바뀔 수 있고, 한도를 올리는 것은 Beta에서 지원하지 않으며 낮추는 것만 가능합니다. 최신 값은 openapi.json과 Deployment 상세의 rate_limits를 함께 확인하세요.
호출 속도
| 구분 | 한도 | 해당하는 요청 |
|---|---|---|
| 접수 | 분당 10회 | Session, Turn, Run 생성과 POST /v1/files |
| 조회 | 분당 60회 | 그 밖의 모든 요청 (조회, 취소, close, 삭제, 다운로드 포함) |
- 한도는 키, Project, Deployment 단위로 각각 적용되며 가장 낮은 쪽이 먼저 걸립니다. 키나 Deployment에 더 낮은 한도를 설정할 수 있습니다.
- 초과하면
429 RATE_LIMITED와Retry-After(초),details.reset_at이 옵니다. - 폴링은 2~5초 간격으로 하고, 가능하면 SSE나 웹훅을 쓰세요.
동시 실행
- Project당 동시 실행은 2개입니다. 이미 접수한 실행은 한도 안에서 대기하고, 새 접수가 한도를 넘으면
429 CONCURRENCY_LIMIT입니다. - 한 Session에는 동시에 Turn 하나만 실행됩니다. (Session과 Turn)
SU 예산
| 구분 | 기본 한도 |
|---|---|
| Turn 하나 | 100 SU |
| Run 하나 (자식 Turn 합산) | 100 SU |
| Project 하루 | 1,000 SU |
| Project 한 달 | 30,000 SU |
- 요청의
limits.max_su로 한 Turn이나 Run의 상한을 더 낮게 정할 수 있습니다. 100을 넘기면422 LIMIT_OUT_OF_RANGE입니다. - Project 하루와 한 달 한도는 UTC 기준 창으로 집계합니다. 넘으면
402 PROJECT_BUDGET_EXCEEDED입니다. - 모델, 검색, 실행 환경, 파일 보관과 전송 비용을 모두 합산합니다. 재시도, 하위 작업의 비용도 한 번씩만 더합니다.
- 비용은 호출 전에 예약하고 끝난 뒤 정산합니다. 정산 전에는
usage.status가PENDING입니다. - 파일 업로드와 다운로드는 계정 잔액이 50 SU 이상일 때 시작할 수 있습니다. 50 SU를 고정 요금으로 차감하지 않으며 실제 사용량만 소모합니다.
입출력 크기
| 항목 | 한도 |
|---|---|
| JSON 요청 본문 | 64KiB |
| metadata | 16개 키, 키 1~64자, 문자열 값 512자 |
| Idempotency-Key | 1~256바이트 |
| TEXT 결과 | 64KiB. 넘으면 파일로 제공 |
| JSON 결과 | 64KiB와 배열 원소 합 100개까지 본문에 포함. 넘으면 파일로 제공. 전체 10MiB, 배열 원소 합 10,000개, 깊이 16까지 |
| 입력 파일 | 개당 20MiB, 한 입력에 20개 |
| 파일 형식 | .txt, .md, .markdown, .csv, .json, .pdf, .png, .jpg, .jpeg, .webp, .docx, .xlsx, .pptx. 확장자와 MIME 형식이 짝이 맞아야 합니다. Deployment가 받는 형식을 더 좁힐 수 있습니다. |
| 결과 파일 | 개당 10MiB, 한 실행에 10개 |
| 한 실행의 파일 합계 | 100MiB |
| Project 파일 보관량 | 500MiB (조직의 남은 저장 용량도 함께 적용) |
| 목록 응답 | 최대 100개, 256KiB. 기본 50개 |
| 웹훅 본문 | 4KiB |
| 다운로드 주소 유효 시간 | 최대 60초 |
| 결과 파일 준비 | 실행 종료 뒤 최대 300초 |
한도를 넘는 값은 조용히 자르지 않고 오류로 거절합니다.
보존
| 대상 | 기간 |
|---|---|
| 멱등 receipt | 최소 24시간, 해당 Turn이 끝나기 전까지 유지. idempotency_expires_at에 정확한 시각이 있습니다. |
| Session | 유휴 30일 (Beta 기본값). Session을 삭제하면 그 Session의 Event, Item, 파일도 함께 삭제됩니다. |
Project에 미리 올린 파일 (POST /v1/files) | 업로드 뒤 24시간. 그 안에 Turn이나 Run 입력으로 쓰지 않으면 만료됩니다. |
| Session 파일 | 올리거나 만든 시점부터 30일. 미리 올린 파일을 Turn 입력으로 쓰면 그 시점부터 30일입니다. Session을 계속 써도 늘어나지 않으므로 Session보다 먼저 만료될 수 있습니다. |
| Run 파일 | Run 기한과 Run 내용 보존 기간까지. 미리 올린 파일을 Run 입력으로 쓰면 이 기간을 따릅니다. |
| Event와 Item 내용 | 최대 30일 |
| Run 내용 | 종결 뒤 기본 30일. 요청의 retention_days(1~30)로 줄일 수 있습니다. |
| 웹훅 중복 제거 ID | 최대 30일(재전송 가능 기간) |
조회는 보존 기간을 늘리지 않습니다. 만료된 내용은 조회 시점에 이미 가려지므로, 정리 작업이 늦어져도 만료된 내용이 보이지 않습니다. 만료되면 410(SESSION_EXPIRED, EVENT_CURSOR_EXPIRED, FILE_EXPIRED 등)이 옵니다. 파일의 정확한 만료 시각은 파일 응답의 expires_at에 있습니다. 필요한 결과는 만료되기 전에 자체 저장소로 옮기세요.
삭제
DELETE /v1/sessions/{session_id}와DELETE /v1/runs/{run_id}는 삭제 접수입니다(202). 응답을 받은 즉시 내용 조회 경로는 막히고 진행 중인 실행은 취소됩니다.- 저장된 입출력, 파일, 대화 기록 등의 물리적 회수는 그 뒤에 비동기로 진행됩니다. Private Beta에서는 완료 시점을 보장하지 않습니다.
- 삭제 요청을 같은
Idempotency-Key로 다시 보내면 내용 없는 삭제 receipt만 돌려줍니다. - 결제와 보안 감사에 필요한 최소 식별자(ID, 시각, 금액, 사유)는 내용 없이 별도로 보존합니다.
- 삭제를 요청해도 이미 일어난 외부 효과는 되돌려지지 않습니다.
보안과 데이터 경계
- 격리: 실행은 Project, Deployment, Session 단위로 나뉩니다. 한 Session의 기억, 파일, 검색 색인이 다른 Session이나 원본 직원에게 복사되지 않습니다.
- 발행 고정: Deployment는 발행 시점의 지침, 스킬, 도구, 모델 등급을 고정합니다. 원본 직원을 고쳐도 영향이 없고, 새 버전은 다시 발행해야 반영됩니다.
- 호출자는 소유자가 아닙니다. API로 부르는 실행은 조직 소유자의 개인 기억(owner memory), 보관 중인 비밀(vault), 로그인해 둔 브라우저를 쓰지 않습니다. 키 scope만으로 이 권한이 늘어나지 않습니다.
- 위험 도구 차단: 허용하지 않은 도구는 호출할 수 없고(
CAPABILITY_DENIED), 임의 위험 도구는 기본으로 막혀 있습니다. 발행본에 비밀 값이 들어 있으면 발행이 거절됩니다. - 공개 응답의 정화: 이벤트와 결과에는 내부 추론, 도구 인자와 결과 원문, 소유자 정보가 들어가지 않습니다. 자유 텍스트의 연락처와 자격 증명 패턴은 가립니다. 임의의 사적 정보를 판별하는 장치는 아니니 입력에 불필요한 개인정보를 넣지 마세요.
- 웹훅: 결과 원문과 파일 주소를 보내지 않고, 내부망 주소로는 전송하지 않습니다.
- 키 보관: 키와 웹훅 secret은 서버의 비밀 저장소에만 두세요.