배치 제출

POST/v1/batches

매트릭스 조합마다 잡을 하나씩 제출합니다

API 키 권한 run 또는 콘솔 세션으로 부릅니다, 콘솔 세션은 조직 역할 owner, admin, developer만 됩니다

매트릭스 순서대로 제출합니다, 첫 조합이 거절되면 아무것도 만들지 않고 그 오류로 실패합니다
이후 조합은 사용 가능 잔액이 (이미 받은 조합 수 + 1) × 1분 요금 이상일 때만 받고, 아니면 그 조합과 나머지를 insufficient_credit로 거절합니다
배치는 git 소스만 받습니다, 최대 잡 수는 기본 20입니다

Headers

Authorization: optional string
Bearer xci_live_… 워크스페이스 API 키, 키 권한 run(read 키는 403 insufficient_permission), 콘솔 세션 쿠키로 대신할 수 있습니다
Origin: optional string
콘솔 세션으로 상태를 바꿀 때 같은 출처(https://xenoci.com)여야 합니다, API 키 요청에는 필요 없습니다
Idempotency-Key: optional string
24시간 안에 같은 키로 다시 보내면 처음 응답을 그대로 돌려줍니다, 같은 키에 다른 본문이면 409 idempotency_conflict
255자 이하

Body

workspace_id: optional string
콘솔 세션은 필수, API 키는 생략하거나 키의 워크스페이스와 같아야 합니다
name: optional string
이름
80자 이하
script: optional string
스크립트
65,536자 이하
recipe_id: optional string
레시피 ID
matrix: BatchMatrix { xcode, simulator, scheme }
축마다 값 목록, 빈 축은 변주하지 않습니다, 조합 순서는 xcode × simulator × scheme
- xcode: optional array of string
  Xcode 버전 축
  최대 10개
- simulator: optional array of string
  시뮬레이터 축
  최대 20개
- scheme: optional array of string
  스킴 축
  최대 20개
env: optional object
환경 변수
timeout_minutes: optional integer
제한 시간(분)
기본값 60, 최소 1, 최대 360
artifacts: optional array of string
결과물 글로브
최대 50개
source: optional object { git_url, ref }
git 소스만 받습니다
- git_url: string
  클론할 Git 저장소 주소
- ref: optional string
  체크아웃할 브랜치, 태그 또는 커밋
repository: optional string
owner/name
runner: optional string
GET /v1/runners 의 러너 ID(기본 macos-m4), status가 available인 러너만 받습니다, 모르는 ID는 400 unknown_runner, coming_soon 러너는 400 runner_not_available
기본값 "macos-m4"

Returns

201 application/json

Batch: object
- id: string
  ID
- organization_id: string
  조직 ID
- workspace_id: string
  워크스페이스 ID
- name: optional string or null
  이름
- recipe_id: optional string or null
  레시피 ID
- status: "running" or "completed" or "cancelled"
  running, completed, cancelled
- matrix: optional BatchMatrix { xcode, simulator, scheme }
  매트릭스
  - xcode: optional array of string
    Xcode 버전 축
    최대 10개
  - simulator: optional array of string
    시뮬레이터 축
    최대 20개
  - scheme: optional array of string
    스킴 축
    최대 20개
- requested_jobs: integer
  요청한 조합 수
- accepted_jobs: integer
  받은 잡 수
- rejected_jobs: integer
  거절된 조합 수
- progress: object { queued, preparing, running, … }
  상태별 잡 수
  - queued: optional integer
    대기 중
  - preparing: optional integer
    준비 중인 잡 수
  - running: optional integer
    실행 중
  - succeeded: optional integer
    성공한 잡 수
  - failed: optional integer
    실패한 잡 수
  - cancelled: optional integer
    취소된 잡 수
  - other_ended: optional integer
    credit_exhausted, platform_error, timed_out으로 끝난 수
  - done: optional integer
    끝난 잡 수
  - percent: optional integer
    done / accepted_jobs, 받은 잡이 없으면 100
    최소 0, 최대 100
- amount_micro_usd: integer
  받은 잡의 금액 합(정산액 또는 실행 중 누적액)
  최소 0
- amount_usd: string
  같은 금액의 USD 문자열(센트, 소수 2자리)
  형식 ^-?[0-9]+\.[0-9]{2}$
- created_at: optional string
  만든 시각
  RFC 3339 UTC 시각
- cancelled_at: optional string or null
  취소 시각
- items: array of BatchItem { index, xcode, simulator, … }
  조합별 항목
  - index: integer
    조합 순번
  - xcode: optional string or null
    Xcode 버전
  - simulator: optional string or null
    시뮬레이터
  - scheme: optional string or null
    스킴
  - job_id: string or null
    제출 때 거절된 조합이면 null
  - status: string
    rejected 또는 그 잡의 상태
  - error: optional object { code, message } or null
    거절 오류
    code: optional string
    오류 코드
    message: optional string
    오류 설명
  - amount_micro_usd: optional integer
    금액(µUSD 정수)
    최소 0
  - amount_usd: optional string
    같은 금액의 USD 문자열(센트, 소수 2자리)
    형식 ^-?[0-9]+\.[0-9]{2}$

오류

invalid_request: HTTP 400
본문이나 쿼리가 검증에 실패했습니다, error.details.fields에 문제 필드가 있습니다
runner_not_available: HTTP 400
준비 중인 러너입니다, status가 available인 러너를 고르세요
unknown_runner: HTTP 400
없는 러너 ID입니다, details.available에 쓸 수 있는 ID가 있습니다
api_key_required: HTTP 401
API 키 엔드포인트에 Authorization: Bearer 헤더가 없습니다
api_key_revoked_leaked: HTTP 401
공개 유출 신고로 자동 폐기된 키입니다, 새 키를 발급하세요
invalid_api_key: HTTP 401
모르는 키이거나 폐기, 만료, 체크섬 불일치입니다(종료된 xeno_ 접두사 포함)
session_required: HTTP 401
콘솔 엔드포인트를 유효한 콘솔 세션 쿠키 없이 불렀습니다
insufficient_credit: HTTP 402
사용 가능 잔액이 현재 요율의 1분어치보다 적습니다, 본문에 잔액과 topup_url이 있습니다
tier_monthly_limit: HTTP 402
조직이 티어 월 사용 한도에 닿았습니다, 다음 달 1일 00:00 UTC 또는 티어 상향 때 풀립니다
workspace_spend_limit: HTTP 402
워크스페이스 월 지출 한도에 닿았습니다, 소유자나 관리자가 올릴 수 있습니다
insufficient_permission: HTTP 403
역할이나 키 권한(run/read)이 이 요청을 허용하지 않습니다
ip_not_allowed: HTTP 403
요청 IP가 조직 또는 API 키의 IP 허용 목록 밖입니다, details.ip와 details.list(organization 또는 api_key)에 있습니다
organization_suspended: HTTP 403
운영자가 조직을 정지했습니다, 키는 거부되고 실행 중인 잡은 멈춥니다
workspace_archived: HTTP 403
보관된 워크스페이스입니다, 키는 폐기되었고 새 잡은 거절됩니다
not_found: HTTP 404
자원이 없거나 이 호출자에게 보이지 않습니다
idempotency_conflict: HTTP 409
같은 Idempotency-Key를 다른 본문으로 다시 썼습니다
rate_limited: HTTP 429, 다시 시도 가능
이 키 또는 조직의 요청이 너무 많습니다, retry_after_s만큼 기다리세요
tier_concurrency_limit: HTTP 429, 다시 시도 가능
실행 중인 잡이 티어 동시 실행 한도에 닿았고 조직 대기열도 가득 찼습니다, retry_after_s 뒤에 다시 보내세요
internal_error: HTTP 500, 다시 시도 가능
예상하지 못한 오류입니다, 다시 시도하고 반복되면 request_id와 함께 알려 주세요
capacity_unavailable: HTTP 503, 다시 시도 가능
설정된 맥 풀 용량이 없습니다, 잡을 받지 않았습니다

오류 봉투 모양과 전체 코드 표는 오류 코드에 있습니다

다음 단계

배치 목록 GET /v1/batches
배치 조회 GET /v1/batches/{batch_id}
배치 취소 POST /v1/batches/{batch_id}/cancel

배치 제출cURL

curl -X POST "https://xenoci.com/api/runner/v1/batches" \
  -H "Authorization: Bearer $XENOCI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"script":"bash ci.sh","source":{"git_url":"https://github.com/acme/ios-app.git","ref":"main"},"matrix":{"xcode":["27.0","26.6"]}}'

Response 201

{
  "id": "bat_5Tk2Wm8Rz1",
  "organization_id": "org_7Kq2m9ZtP3",
  "workspace_id": "wrk_3fK9Qm2Zp8",
  "name": "xcode-matrix",
  "recipe_id": null,
  "status": "running",
  "matrix": {
    "xcode": [
      "27.0",
      "26.6"
    ]
  },
  "requested_jobs": 2,
  "accepted_jobs": 2,
  "rejected_jobs": 0,
  "progress": {
    "queued": 0,
    "preparing": 0,
    "running": 1,
    "succeeded": 1,
    "failed": 0,
    "cancelled": 0,
    "other_ended": 0,
    "done": 1,
    "percent": 50
  },
  "amount_micro_usd": 160000,
  "amount_usd": "0.16",
  "created_at": "2026-10-12T03:11:05Z",
  "cancelled_at": null,
  "items": [
    {
      "index": 0,
      "xcode": "27.0",
      "simulator": null,
      "scheme": null,
      "job_id": "job_2Qm7Xp9Lk4",
      "status": "succeeded",
      "error": null,
      "amount_micro_usd": 80000,
      "amount_usd": "0.08"
    }
  ]
}