> ## Documentation Index > Fetch the complete documentation index at: https://docs.trychainshift.ai/llms.txt > Use this file to discover all available pages before exploring further. # 실행 요청 > 조직의 프롬프트를 지정한 모델로 실행합니다. 정기 모니터링이 아니라 요청한 시점에 한 번 수행됩니다. 요청이 성공하면 프롬프트 실행(Run)이 생성됩니다. 실행 대상은 promptIDs(개별 프롬프트) 또는 promptSetID(프롬프트 세트 전체) 중 하나만 지정할 수 있으며, 둘을 동시에 사용할 수 없습니다. 진행 상태는 응답으로 받은 id를 사용해 프롬프트 실행 상태 조회에서 확인합니다. ### 오류 | HTTP | 코드 | 설명 | | --- | --- | --- | | 400 | `COMMON_BINDING` | • 요청 본문 JSON 파싱 실패 • promptIDs·promptSetID 형식 오류 (details 에 `PLATFORM_INVALID_ID`) | | 400 | `COMMON_VALIDATION` | • models 누락·8개 초과 • promptIDs 500개 초과 • repeatCount 범위 위반(1~100) | | 400 | `RUN_PROMPT_TARGET_REQUIRED` | promptIDs·promptSetID 중 정확히 하나를 지정하지 않음 | | 400 | `PROMPT_SET_EMPTY` | 지정한 세트에 실행할 프롬프트가 없음 | | 400 | `MODEL_NOT_SUPPORTED` | 플랫폼 API 가 지원하지 않는 model 값 | | 400 | `NO_AVAILABLE_PLATFORM` | 요청한 모델이 현재 모두 수집 불가 | | 400 | `REGION_NOT_SUPPORTED` | 지원하지 않는 지역 코드 | | 400 | `REGION_NOT_SUPPORTED_FOR_MODEL` | 모델이 지원하지 않는 지역 | | 400 | `QUESTION_NOT_MARKETING_PLATFORM` | 플랫폼 API 소속이 아닌 프롬프트 | | 400 | `RUN_TOO_MANY_TASKS` | 총 실행 수(프롬프트 × 모델 × 반복)가 10,000 초과 | | 401 | `COMMON_UNAUTHORIZED` | API 키 또는 액세스 토큰이 없거나 유효하지 않음 | | 402 | `INSUFFICIENT_CREDITS` | 조직 크레딧 잔액이 이 요청의 단가보다 적음 | | 403 | `MODEL_NOT_GRANTED` | 별도 계약이 필요한 모델을 권한 없이 요청함 (`GET /models` 에도 나타나지 않음) | | 404 | `PROMPT_NOT_FOUND` | 프롬프트가 없거나 타 조직 소유 | | 404 | `PROMPT_SET_NOT_FOUND` | 세트가 없거나 타 조직 소유 | | 404 | `CAMPAIGN_NOT_FOUND` | 프롬프트가 속한 캠페인을 찾을 수 없음 | | 429 | `PLATFORM_RATE_LIMIT_EXCEEDED` | 요청 한도 초과. `Retry-After` 헤더의 초만큼 기다린 뒤 재시도 | | 500 | — | 서버 내부 오류. `code` 없이 `message` 와 `requestID` 를 반환 | 전체 흐름(프롬프트 준비 → 제출 → 폴링 → 답변 조회)과 폴링 루프 코드는 [프롬프트 실행하기](/guides/submitting-runs) 가이드를 참고하세요. ## 자주 묻는 질문 **제출 후 결과는 어디서 받나요?** 반환된 `runID`로 [실행 상태 조회](/api-reference/runs/get-run-status)를 폴링하고, `FINISHED`가 되면 [답변 목록](/api-reference/answers/list-answers)을 `runID` 필터로 조회합니다. ## OpenAPI ````yaml POST /v1/platform/runs openapi: 3.1.0 info: description: >- 외부 파트너용 플랫폼 API. 조직 API 키 기반 인증을 사용합니다. ### 공통 요청 제한 - 요청 body 크기는 최대 2MiB이며, 초과 시 413과 함께 `COMMON_REQUEST_BODY_TOO_LARGE` 코드를 반환합니다. - 배열 파라미터와 문자열 필드에는 엔드포인트별 개수·길이 상한이 있습니다. 상한은 각 필드/파라미터 설명에 명시되어 있으며, 위반 시 400과 함께 `COMMON_VALIDATION` 코드를 반환합니다. ### 오류 응답 오류 응답 본문은 상태 코드와 상관없이 항상 같은 세 필드입니다. | 필드 | 형태 | 의미 | | --- | --- | --- | | `code` | 문자열 | 오류 종류를 가리키는 고정 식별자입니다. 클라이언트가 분기할 대상은 이 값 하나입니다. 엔드포인트가 반환하는 코드 목록은 각 API 의 "오류" 표에 있습니다. | | `message` | 문자열 | 오류 전체를 한 줄로 요약한, 사람이 읽는 문장입니다. 언제나 한 개입니다. | | `details` | 문자열 배열 | `message` 한 줄로는 부족한 개별 사유입니다. 사유가 한 건이어도 길이 1 배열로 내려가며, 담을 사유가 없으면 필드 자체가 빠집니다. | - `details` 는 어떤 오류에서도 배열입니다. 문자열이나 객체로 내려오는 경우는 없으므로 형태별 분기가 필요 없습니다. - `details` 의 문구 자체는 고정 계약이 아닙니다. 화면 표시와 디버깅에만 쓰고, 문자열을 파싱해 분기하지 마십시오. 분기는 `code` 로 하십시오. - 여러 건의 사유를 담는 필드는 `details` 하나뿐입니다. `messages` 라는 필드는 응답에 존재하지 않습니다. - 검증 실패(`COMMON_VALIDATION`) 시 `details` 에는 위반 필드마다 `"필드: 사유"` 한 줄씩 담깁니다. 예: `{"code":"COMMON_VALIDATION","message":"데이터 검증에 실패했습니다","details":["keywords: 최대 100개까지 입력할 수 있습니다"]}` - `message` 는 기본이 한국어이고, `Accept-Language: en` 을 보내면 영어로 제공됩니다. `details` 도 검증 실패처럼 필드별 사유를 담는 경우에는 같은 규칙을 따르지만, 진단 목적으로 원문을 그대로 싣는 오류에서는 요청 언어와 다른 문구가 담길 수 있습니다. - 500 만 형태가 다릅니다. `code` 없이 `message` 와, 문의 시 참조할 `requestID` 를 반환합니다. title: Platform API version: '1.0' servers: - url: https://platform-api.trychainshift.ai/api security: [] tags: - description: API 키가 귀속되는 최상위 계정 단위입니다. 조직의 기본 정보를 조회합니다. name: Organization - description: AI 서비스에서 노출을 모니터링하는 대상 브랜드입니다. 브랜드 등록·조회·수정·삭제를 제공합니다. name: Brand - description: >- 브랜드와 시장을 분석하기 위한 키워드 인텔리전스입니다. 구글·네이버 검색 지표, 연관·자동완성 키워드 조회와 사이트 URL 기반 키워드 분석을 제공합니다. name: Keyword (Beta) - description: 프롬프트를 목적별로 묶는 그룹입니다. 프롬프트 세트 생성·조회·수정·삭제를 제공합니다. name: PromptSet - description: AI 서비스에 질의하는 문장 단위입니다. 프롬프트 생성·조회·수정·삭제와 대량 생성을 제공합니다. name: Prompt - description: 프롬프트 실행에 사용하는 AI 서비스 모델입니다. 지원 모델 목록을 조회합니다. name: Model - description: 프롬프트 실행에 사용하는 실행 지역입니다. 지원 리전 목록을 조회합니다. name: Region - description: 프롬프트를 AI 서비스에 실제로 실행하는 작업 단위입니다. 프롬프트 실행 요청과 진행 상태·목록 조회를 제공합니다. name: Run - description: 실행으로 수집된 AI 서비스의 응답입니다. 인용 출처·검색 쿼리를 포함한 답변을 조회합니다. name: Answer - description: 답변에 인용된 출처의 도메인·URL 단위 통계 지표입니다. 인용 요약, 도메인별·URL별 인용 통계를 조회합니다. name: SourceStatistics (Beta) - description: 답변 본문의 토큰(Kiwi 명사) 통계 지표입니다. 많이 나온 토큰 랭킹과 특정 단어의 근접 토큰을 조회합니다. name: AnswerStatistics (Beta) - description: AI가 답변 생성 시 실제로 던진 검색 쿼리(팬아웃) 통계 지표입니다. 검색 쿼리별 등장 횟수 랭킹을 조회합니다. name: FanoutStatistics (Beta) - description: 텍스트에서 고유명사를 식별하는 부가 기능입니다. 고유명사 추출을 제공합니다. name: ProperNoun (Beta) - description: 조직 크레딧 잔액 및 플랫폼 API 과금 정보입니다. 현재 크레딧 잔액을 조회합니다. name: Credit externalDocs: description: '' url: '' paths: /v1/platform/runs: post: tags: - Run summary: 프롬프트 실행 요청 description: >- 조직의 프롬프트를 지정한 모델로 실행합니다. 정기 모니터링이 아니라 요청한 시점에 한 번 수행됩니다. 요청이 성공하면 프롬프트 실행(Run)이 생성됩니다. 실행 대상은 promptIDs(개별 프롬프트) 또는 promptSetID(프롬프트 세트 전체) 중 하나만 지정할 수 있으며, 둘을 동시에 사용할 수 없습니다. 진행 상태는 응답으로 받은 id를 사용해 프롬프트 실행 상태 조회에서 확인합니다. ### 오류 | HTTP | 코드 | 설명 | | --- | --- | --- | | 400 | `COMMON_BINDING` | • 요청 본문 JSON 파싱 실패 • promptIDs·promptSetID 형식 오류 (details 에 `PLATFORM_INVALID_ID`) | | 400 | `COMMON_VALIDATION` | • models 누락·8개 초과 • promptIDs 500개 초과 • repeatCount 범위 위반(1~100) | | 400 | `RUN_PROMPT_TARGET_REQUIRED` | promptIDs·promptSetID 중 정확히 하나를 지정하지 않음 | | 400 | `PROMPT_SET_EMPTY` | 지정한 세트에 실행할 프롬프트가 없음 | | 400 | `MODEL_NOT_SUPPORTED` | 플랫폼 API 가 지원하지 않는 model 값 | | 400 | `NO_AVAILABLE_PLATFORM` | 요청한 모델이 현재 모두 수집 불가 | | 400 | `REGION_NOT_SUPPORTED` | 지원하지 않는 지역 코드 | | 400 | `REGION_NOT_SUPPORTED_FOR_MODEL` | 모델이 지원하지 않는 지역 | | 400 | `QUESTION_NOT_MARKETING_PLATFORM` | 플랫폼 API 소속이 아닌 프롬프트 | | 400 | `RUN_TOO_MANY_TASKS` | 총 실행 수(프롬프트 × 모델 × 반복)가 10,000 초과 | | 401 | `COMMON_UNAUTHORIZED` | API 키 또는 액세스 토큰이 없거나 유효하지 않음 | | 402 | `INSUFFICIENT_CREDITS` | 조직 크레딧 잔액이 이 요청의 단가보다 적음 | | 403 | `MODEL_NOT_GRANTED` | 별도 계약이 필요한 모델을 권한 없이 요청함 (`GET /models` 에도 나타나지 않음) | | 404 | `PROMPT_NOT_FOUND` | 프롬프트가 없거나 타 조직 소유 | | 404 | `PROMPT_SET_NOT_FOUND` | 세트가 없거나 타 조직 소유 | | 404 | `CAMPAIGN_NOT_FOUND` | 프롬프트가 속한 캠페인을 찾을 수 없음 | | 429 | `PLATFORM_RATE_LIMIT_EXCEEDED` | 요청 한도 초과. `Retry-After` 헤더의 초만큼 기다린 뒤 재시도 | | 500 | — | 서버 내부 오류. `code` 없이 `message` 와 `requestID` 를 반환 | operationId: submitPlatformRun requestBody: content: application/json: schema: $ref: '#/components/schemas/domain.SubmitRunRequest' description: 프롬프트 실행 요청 required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/domain.SubmitRunResponse' description: OK '400': content: application/json: schema: $ref: '#/components/schemas/domain.ValidationError' description: >- models 누락·8개 초과, promptIDs 500개 초과, repeatCount 범위 위반(1~100). 실행 대상·모델·지역 관련 400 코드는 위 오류 표 참고 '401': content: application/json: schema: $ref: '#/components/schemas/domain.UnauthorizedError' description: API 키 또는 액세스 토큰이 없거나 유효하지 않습니다 '402': content: application/json: schema: $ref: '#/components/schemas/domain.InsufficientCreditsError' description: 실행 규모(모델×프롬프트×반복)에 필요한 크레딧이 잔액보다 큽니다 '403': content: application/json: schema: $ref: '#/components/schemas/domain.ModelNotGrantedError' description: 별도 계약이 필요한 모델입니다. 조직에 부여되지 않았습니다 '404': content: application/json: schema: $ref: '#/components/schemas/domain.PromptNotFoundError' description: >- 프롬프트(PROMPT_NOT_FOUND) 또는 프롬프트 세트(PROMPT_SET_NOT_FOUND)를 찾을 수 없습니다 (다른 조직 소유 포함) '429': content: application/json: schema: $ref: '#/components/schemas/domain.RateLimitExceededError' description: 요청 한도를 초과했습니다. Retry-After 헤더의 초만큼 기다린 뒤 재시도하세요 '500': content: application/json: schema: $ref: '#/components/schemas/domain.InternalServerError' description: 서버 내부 오류. requestID 를 함께 알려주시면 추적할 수 있습니다 security: - OrgAPIKeyAuth: [] components: schemas: domain.SubmitRunRequest: properties: models: description: 실행할 모델 목록. example: - CHATGPT - PERPLEXITY items: $ref: '#/components/schemas/domain.RunModel' maxItems: 8 minItems: 1 type: array uniqueItems: false promptIDs: description: 실행할 프롬프트 ID 목록 (1~500개, 중복은 1회로 처리). promptSetID 와 정확히 하나만 지정합니다 example: - cM0RPoxbNbJy0mS-MhsHOg items: type: string maxItems: 500 minItems: 1 type: array uniqueItems: false promptSetID: description: >- 실행할 프롬프트 세트 ID — 세트 소속 프롬프트 전체를 실행합니다. promptIDs 와 정확히 하나만 지정합니다. 세트 프롬프트 수에 500개 제한은 없으며 총 실행 수 상한(10,000)만 적용 example: IkVMHhjFWcBXcJ41-h9yBQ type: string region: description: >- 실행 지역(ISO 3166-1 alpha-2). 생략 시 KR. 지원하지 않는 코드는 400. 모델마다 지원 지역이 다를 수 있습니다.(GET /regions?model= 로 확인) example: KR type: string repeatCount: description: 각 프롬프트(question)별 반복 실행 횟수 (기본 1, 최대 100). example: 1 maximum: 100 minimum: 1 type: integer required: - models type: object domain.SubmitRunResponse: properties: id: description: >- 생성된 프롬프트 실행의 ID. 이 값을 프롬프트 실행 상태 조회(GET /v1/platform/runs/{runID})의 runID 로 그대로 넣습니다 example: S8cqDSjSot67bCK6YtmvHw type: string type: object domain.ValidationError: properties: code: description: 오류 코드 example: COMMON_VALIDATION type: string details: description: '위반한 필드별 사유 목록 ("필드: 사유" 한 줄씩)' example: - 'limit: 100 이하여야 합니다' items: type: string type: array uniqueItems: false message: description: '오류 메시지 (기본 한국어, Accept-Language: en 지정 시 영어)' example: 데이터 검증에 실패했습니다 type: string type: object domain.UnauthorizedError: properties: code: description: 오류 코드 example: COMMON_UNAUTHORIZED type: string message: description: '오류 메시지 (기본 한국어, Accept-Language: en 지정 시 영어)' example: 인증되지 않은 사용자입니다 type: string type: object domain.InsufficientCreditsError: properties: code: description: 오류 코드 example: INSUFFICIENT_CREDITS type: string message: description: '오류 메시지 (기본 한국어, Accept-Language: en 지정 시 영어)' example: 크레딧이 부족합니다. type: string type: object domain.ModelNotGrantedError: properties: code: description: 오류 코드 example: MODEL_NOT_GRANTED type: string message: description: '오류 메시지 (기본 한국어, Accept-Language: en 지정 시 영어)' example: 조직에 부여되지 않은 모델입니다. 사용하려면 계약이 필요합니다 type: string type: object domain.PromptNotFoundError: properties: code: description: 오류 코드 example: PROMPT_NOT_FOUND type: string message: description: '오류 메시지 (기본 한국어, Accept-Language: en 지정 시 영어)' example: 프롬프트를 찾을 수 없습니다 type: string type: object domain.RateLimitExceededError: properties: code: description: 오류 코드 example: PLATFORM_RATE_LIMIT_EXCEEDED type: string message: description: '오류 메시지 (기본 한국어, Accept-Language: en 지정 시 영어)' example: 요청이 너무 많습니다. 잠시 후 다시 시도해주세요. type: string type: object domain.InternalServerError: properties: message: description: 오류 메시지 (지역화하지 않습니다) example: Internal Server Error type: string requestID: description: 문의 시 참조할 요청 식별자 (응답의 X-Request-Id 헤더와 같은 값) example: bkZqnHQepkgTOocTvyHWSlHcGzRqQbZk type: string type: object domain.RunModel: enum: - CHATGPT - GOOGLE_OVERVIEW - GOOGLE_AI - PERPLEXITY - GEMINI - NAVER_AI_BRIEFING - NAVER_AI_TAB - CLAUDE type: string x-enum-varnames: - RunModelChatGPT - RunModelGoogleOverview - RunModelGoogleAI - RunModelPerplexity - RunModelGemini - RunModelNaverAIBriefing - RunModelNaverAITab - RunModelClaude securitySchemes: OrgAPIKeyAuth: description: '"조직 API 키를 입력하세요. 예: ''cs_live_xxxx''"' in: header name: API-Key type: apiKey ````