배치 제출

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

POST /v1/batches

인증

방식	허용	조건
API 키 (`Authorization: Bearer xci_live_…`)	가능	키 권한 `run` (read 키는 403 insufficient_permission)
콘솔 세션 쿠키	가능	조직 역할 `owner`, `admin`, `developer`, 같은 출처의 Origin 헤더 필요

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

매개변수

이름	위치	타입	필수	설명
`Idempotency-Key`	헤더	string		24시간 안에 같은 키로 다시 보내면 처음 응답을 그대로 돌려줍니다, 같은 키에 다른 본문이면 409 idempotency_conflict, 1자 이상, 255자 이하

요청 본문

필드	타입	필수	설명
`workspace_id`	string		콘솔 세션은 필수, API 키는 생략하거나 키의 워크스페이스와 같아야 합니다
`name`	string		이름, 80자 이하
`script`	string		스크립트, 1자 이상, 65536자 이하
`recipe_id`	string		레시피 ID
`matrix`	object	필수	축마다 값 목록, 빈 축은 변주하지 않습니다, 조합 순서는 xcode × simulator × scheme
`matrix.xcode`	array<string>		Xcode 버전 축, 최대 10개
`matrix.simulator`	array<string>		시뮬레이터 축, 최대 20개
`matrix.scheme`	array<string>		스킴 축, 최대 20개
`env`	object		환경 변수
`timeout_minutes`	integer		제한 시간(분), 최소 1, 최대 360, 기본 `60`
`artifacts`	array<string>		결과물 글로브, 최대 50개
`source`	object		git 소스만 받습니다
`source.git_url`	string	필수
`source.ref`	string
`repository`	string		owner/name

응답

201

필드	타입	항상	설명
`id`	string	항상	ID
`organization_id`	string	항상	조직 ID
`workspace_id`	string	항상	워크스페이스 ID
`name`	string		이름, null 가능
`recipe_id`	string		레시피 ID, null 가능
`status`	`running` \| `completed` \| `cancelled`	항상	running, completed, cancelled
`matrix`	object		매트릭스
`matrix.xcode`	array<string>		Xcode 버전 축, 최대 10개
`matrix.simulator`	array<string>		시뮬레이터 축, 최대 20개
`matrix.scheme`	array<string>		스킴 축, 최대 20개
`requested_jobs`	integer	항상	요청한 조합 수
`accepted_jobs`	integer	항상	받은 잡 수
`rejected_jobs`	integer	항상	거절된 조합 수
`progress`	object	항상	상태별 잡 수
`progress.queued`	integer		대기 중
`progress.preparing`	integer
`progress.running`	integer		실행 중
`progress.succeeded`	integer
`progress.failed`	integer
`progress.cancelled`	integer
`progress.other_ended`	integer		creditexhausted, platformerror, timed_out으로 끝난 수
`progress.done`	integer		끝난 잡 수
`progress.percent`	integer		done / accepted_jobs, 받은 잡이 없으면 100, 최소 0, 최대 100
`amount_micro_usd`	integer	항상	받은 잡의 금액 합(정산액 또는 실행 중 누적액), 최소 0
`amount_usd`	string	항상	같은 금액의 USD 문자열(소수 6자리), 형식 `^-?[0-9]+\.[0-9]{6}$`
`created_at`	timestamp		만든 시각
`cancelled_at`	string		취소 시각
`items`	array<object>	항상	조합별 항목
`items[].index`	integer	항상	조합 순번
`items[].xcode`	string		Xcode 버전, null 가능
`items[].simulator`	string		시뮬레이터, null 가능
`items[].scheme`	string		스킴, null 가능
`items[].job_id`	string	항상	제출 때 거절된 조합이면 null, null 가능
`items[].status`	string	항상	rejected 또는 그 잡의 상태
`items[].error`	string		거절 오류
`items[].amount_micro_usd`	integer		금액(µUSD 정수), 최소 0
`items[].amount_usd`	string		같은 금액의 USD 문자열(소수 6자리), 형식 `^-?[0-9]+\.[0-9]{6}$`

{
  "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": 158400,
  "amount_usd": "0.158400",
  "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": 118800,
      "amount_usd": "0.118800"
    }
  ]
}

오류

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

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

예시

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"]}}'

다음 단계

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