프롬프트 실행하기

프롬프트 실행은 비동기로 동작합니다. 제출하면 runID가 즉시 반환되고, 수집은 백그라운드에서 진행됩니다. 완료 여부는 폴링으로 확인합니다.

1. 프롬프트 준비

프롬프트는 반드시 프롬프트 세트에 속하므로, 세트를 먼저 만듭니다.

curl -X POST "https://dev-platform-api.trychainshift.ai/api/v1beta/platform/prompt-sets" \
  -H "API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "중고차 GEO 모니터링"}'

{ "id": "Jix75RbQ2gfTB0qzlh125g" }

반환된 세트 ID로 프롬프트를 등록합니다. 프롬프트는 실제 사용자가 AI에 물어볼 법한 질문 그대로 씁니다. 여러 개를 한 번에 등록하려면 POST /prompts/bulk(최대 100개)를 사용하세요.

curl -X POST "https://dev-platform-api.trychainshift.ai/api/v1beta/platform/prompts" \
  -H "API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promptSetID": "Jix75RbQ2gfTB0qzlh125g",
    "content": "2000만원대 중고 SUV 추천해줘"
  }'

{ "id": "W-KMZMXwDB7ihFtj5CMHSQ" }

2. 실행 요청

프롬프트 지정 방법은 두 가지이며, 정확히 하나만 사용해야 합니다.

promptIDs — 개별 프롬프트 ID 목록 (1~500개)
promptSetID — 세트에 속한 모든 프롬프트를 실행

curl -X POST "https://dev-platform-api.trychainshift.ai/api/v1beta/platform/runs" \
  -H "API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promptSetID": "Jix75RbQ2gfTB0qzlh125g",
    "models": ["CHATGPT", "PERPLEXITY", "GEMINI", "NAVER_AI_BRIEFING", "NAVER_AI_TAB"],
    "repeatCount": 5
  }'

curl -X POST "https://dev-platform-api.trychainshift.ai/api/v1beta/platform/runs" \
  -H "API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promptIDs": ["W-KMZMXwDB7ihFtj5CMHSQ"],
    "models": ["CHATGPT", "PERPLEXITY"]
  }'

{ "runID": "GULjgaLy-DjX9NAVxjZBFg" }

파라미터	필수	설명
`models`	필수	실행할 AI 모델 1~20개. 사용 가능한 값은 지원 모델 참고
`promptIDs`	택일	실행할 프롬프트 ID 1~500개
`promptSetID`	택일	세트 전체 실행. 빈 세트는 `PROMPT_SET_EMPTY` 에러
`region`	선택	답변을 수집할 지역. 생략 시 `KR`
`repeatCount`	선택	프롬프트 × 모델 조합당 반복 횟수 (1~100). 생략 시 1

AI 답변은 실행마다 달라지므로, 언급률처럼 비율로 보는 지표는 repeatCount를 2 이상으로 두어야 의미가 있습니다. 1회 실행 결과는 답변 내용·인용 출처를 눈으로 확인할 때 쓰세요.

총 실행 수(프롬프트 수 × 모델 수 × repeatCount)는 실행 요청 하나당 10,000개를 넘을 수 없습니다. 초과하면 RUN_TOO_MANY_TASKS 에러가 반환됩니다. 과금 방식은 Rate Limit & 크레딧을 참고하세요.

3. 완료 폴링

status가 FINISHED가 될 때까지 조회합니다. 수집은 보통 수 분이 걸리므로 30초 정도 간격의 폴링을 권장합니다.

curl -H "API-Key: YOUR_API_KEY" \
  "https://dev-platform-api.trychainshift.ai/api/v1beta/platform/runs/GULjgaLy-DjX9NAVxjZBFg"

아래는 실제 수집 응답입니다(answers 배열은 두 건만 남겼습니다).

{
  "runID": "GULjgaLy-DjX9NAVxjZBFg",
  "status": "FINISHED",
  "totalCount": 100,
  "finishedCount": 100,
  "successCount": 63,
  "failedCount": 37,
  "runningCount": 0,
  "answers": [
    {
      "promptID": "RWWJZHPxJ0QEroVpj-3yDQ",
      "model": "PERPLEXITY",
      "region": "KR",
      "query": "중고차 직거래랑 딜러 거래 중에 뭐가 나아?",
      "status": "SUCCESS"
    },
    {
      "promptID": "W-KMZMXwDB7ihFtj5CMHSQ",
      "model": "NAVER_AI_TAB",
      "region": "KR",
      "query": "2000만원대 중고 SUV 추천해줘",
      "status": "FAILED"
    }
  ]
}

응답을 읽는 법:

진행 중에는 status가 RUNNING이고 runningCount가 남은 실행 수를 보여줍니다. 두 값이 FINISHED / 0이 되면 수집이 끝난 것입니다.
개별 실행이 실패해도 실행 요청은 FINISHED로 끝납니다. 위 예시는 100개 실행 중 37개가 실패한 실제 사례입니다 — 특정 모델이 일시적으로 응답하지 않는 일은 드물지 않습니다.
answers 항목은 실행별 진행 상태(PENDING/SUCCESS/FAILED)만 담습니다. 답변 본문은 다음 단계의 답변 API로 가져옵니다.

실패한 실행(FAILED)은 답변이 생성되지 않으며, 크레딧도 차감되지 않습니다. 재수집이 필요하면 해당 프롬프트로 다시 실행을 요청하세요.

AI 답변은 비결정적입니다. 같은 프롬프트 × 모델 조합도 실행마다 내용과 출처가 달라질 수 있습니다. 브랜드 노출률처럼 확률적인 지표를 측정할 때는 repeatCount로 같은 조합을 반복 실행하세요.

폴링 루프 예시

import os, time, requests

API = "https://dev-platform-api.trychainshift.ai/api/v1beta/platform"
HEADERS = {"API-Key": os.environ["CHAINSHIFT_API_KEY"]}

run_id = requests.post(f"{API}/runs", headers=HEADERS, json={
    "promptSetID": "Jix75RbQ2gfTB0qzlh125g",
    "models": ["CHATGPT", "PERPLEXITY"],
}).json()["runID"]

while True:
    status = requests.get(f"{API}/runs/{run_id}", headers=HEADERS).json()
    if status["status"] == "FINISHED":
        break
    time.sleep(30)

answers = requests.get(f"{API}/answers", headers=HEADERS,
                       params={"runID": run_id, "status": "SUCCESS"}).json()

const API = "https://dev-platform-api.trychainshift.ai/api/v1beta/platform";
const headers = { "API-Key": process.env.CHAINSHIFT_API_KEY, "Content-Type": "application/json" };

const { runID } = await (await fetch(`${API}/runs`, {
  method: "POST",
  headers,
  body: JSON.stringify({ promptSetID: "Jix75RbQ2gfTB0qzlh125g", models: ["CHATGPT", "PERPLEXITY"] }),
})).json();

let status;
do {
  await new Promise((r) => setTimeout(r, 30_000));
  status = await (await fetch(`${API}/runs/${runID}`, { headers })).json();
} while (status.status !== "FINISHED");

const answers = await (await fetch(`${API}/answers?runID=${runID}&status=SUCCESS`, { headers })).json();

4. 답변 가져오기

수집이 끝나면 답변 본문과 출처를 조회합니다.

curl -H "API-Key: YOUR_API_KEY" \
  "https://dev-platform-api.trychainshift.ai/api/v1beta/platform/answers?runID=GULjgaLy-DjX9NAVxjZBFg"

필터와 응답 구조는 답변 수집하기를 참고하세요.

에러 케이스

{
  "code": "RUN_PROMPT_TARGET_REQUIRED",
  "message": "promptIDs 또는 promptSetID 중 정확히 하나를 지정해야 합니다"
}

코드	HTTP	원인
`RUN_PROMPT_TARGET_REQUIRED`	400	`promptIDs`·`promptSetID`를 둘 다 생략했거나 둘 다 지정
`RUN_TOO_MANY_TASKS`	400	총 실행 수가 10,000개 초과
`PROMPT_SET_EMPTY`	400	빈 프롬프트 세트로 제출
`MODEL_NOT_SUPPORTED`	400	지원하지 않는 모델 값
`REGION_NOT_SUPPORTED_FOR_MODEL`	400	해당 모델이 지원하지 않는 지역
`INSUFFICIENT_CREDITS`	402	크레딧 잔액 부족

운영 팁

실행 목록은 GET /runs로 최신순 조회합니다(페이지 크기 최대 10).
같은 프롬프트를 정기적으로 수집하려면 세트를 만들어 두고 promptSetID로 반복 제출하는 방식이 간단합니다.
모델별 fan-out 지원 여부 등 수집 특성은 지원 모델에서 확인하세요.

시작하기

인증

가이드

MCP

프롬프트 실행하기

1. 프롬프트 준비

2. 실행 요청

3. 완료 폴링

폴링 루프 예시

4. 답변 가져오기

에러 케이스

운영 팁

​1. 프롬프트 준비

​2. 실행 요청

​3. 완료 폴링

​폴링 루프 예시

​4. 답변 가져오기

​에러 케이스

​운영 팁

1. 프롬프트 준비

2. 실행 요청

3. 완료 폴링

폴링 루프 예시

4. 답변 가져오기

에러 케이스

운영 팁