> ## 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.

# 답변 목록

> 프롬프트를 실행해서 얻은 답변 목록을 조회합니다. 각 답변은 본문과 함께 인용(sources)·팬아웃(fanouts)·원본 마크다운(markdownURL)을 포함하며, PENDING/FAILED 실행도 상태와 함께 반환됩니다.

`markdownURL` 은 `status` 가 `SUCCESS` 인 답변에 항상 포함됩니다. 수집 전(`PENDING`)·수집 실패(`FAILED`) 답변에만 원본이 없어 생략되므로, `SUCCESS` 답변을 다룰 때 값이 없는 경우를 대비할 필요는 없습니다.

### 오류

| HTTP | 코드 | 설명 |
| --- | --- | --- |
| 400 | `COMMON_VALIDATION` | • limit 범위 위반(1~100) • 지원하지 않는 status 값 |
| 400 | `COMMON_INVALID_CURSOR` | cursor 형식 오류 |
| 400 | `COMMON_BINDING` | runID·promptSetID·promptID 형식 오류 (details 에 `PLATFORM_INVALID_ID`) |
| 401 | `COMMON_UNAUTHORIZED` | API 키 또는 액세스 토큰이 없거나 유효하지 않음 |
| 402 | `INSUFFICIENT_CREDITS` | 조직 크레딧 잔액이 이 요청의 단가보다 적음 |
| 429 | `PLATFORM_RATE_LIMIT_EXCEEDED` | 요청 한도 초과. `Retry-After` 헤더의 초만큼 기다린 뒤 재시도 |
| 500 | — | 서버 내부 오류. `code` 없이 `message` 와 `requestID` 를 반환 |

응답 필드의 의미와 빈 값 규칙(`fanouts`·`sources`가 언제 비는지)은 [답변 객체](/api-reference/answers/answer-object)를, 실제 응답 예시와 해석은 [답변 조회하기](/guides/collecting-answers) 가이드를 참고하세요.


## OpenAPI

````yaml GET /v1/platform/answers
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/answers:
    get:
      tags:
        - Answer
      summary: 답변 목록 조회
      description: >-
        프롬프트를 실행해서 얻은 답변 목록을 조회합니다. 각 답변은 본문과 함께 인용(sources)·팬아웃(fanouts)·원본
        마크다운(markdownURL)을 포함하며, PENDING/FAILED 실행도 상태와 함께 반환됩니다.


        `markdownURL` 은 `status` 가 `SUCCESS` 인 답변에 항상 포함됩니다. 수집 전(`PENDING`)·수집
        실패(`FAILED`) 답변에만 원본이 없어 생략되므로, `SUCCESS` 답변을 다룰 때 값이 없는 경우를 대비할 필요는
        없습니다.


        ### 오류


        | HTTP | 코드 | 설명 |

        | --- | --- | --- |

        | 400 | `COMMON_VALIDATION` | • limit 범위 위반(1~100) • 지원하지 않는 status 값 |

        | 400 | `COMMON_INVALID_CURSOR` | cursor 형식 오류 |

        | 400 | `COMMON_BINDING` | runID·promptSetID·promptID 형식 오류 (details 에
        `PLATFORM_INVALID_ID`) |

        | 401 | `COMMON_UNAUTHORIZED` | API 키 또는 액세스 토큰이 없거나 유효하지 않음 |

        | 402 | `INSUFFICIENT_CREDITS` | 조직 크레딧 잔액이 이 요청의 단가보다 적음 |

        | 429 | `PLATFORM_RATE_LIMIT_EXCEEDED` | 요청 한도 초과. `Retry-After` 헤더의 초만큼
        기다린 뒤 재시도 |

        | 500 | — | 서버 내부 오류. `code` 없이 `message` 와 `requestID` 를 반환 |
      operationId: listAnswers
      parameters:
        - description: 특정 프롬프트 실행으로 범위를 좁히는 필터 (실행 요청 시 발급된 ID)
          example: S8cqDSjSot67bCK6YtmvHw
          in: query
          name: runID
          schema:
            type: string
        - description: 특정 프롬프트 세트로 범위를 좁히는 필터 (세트 목록·생성 응답의 id)
          example: IkVMHhjFWcBXcJ41-h9yBQ
          in: query
          name: promptSetID
          schema:
            type: string
        - description: 특정 프롬프트로 범위를 좁히는 필터 (프롬프트 목록·생성 응답의 id)
          example: KNUETdAfRhDY9lQTgu9wuw
          in: query
          name: promptID
          schema:
            type: string
        - description: 특정 모델로 범위를 좁히는 필터
          example: CHATGPT
          in: query
          name: model
          schema:
            type: string
        - description: 특정 지역으로 범위를 좁히는 필터
          example: KR
          in: query
          name: region
          schema:
            type: string
        - description: >-
            수집·분류 상태 필터. PENDING(아직 답변 미준비), SUCCESS(답변 분류 완료), FAILED(실패 또는
            건너뜀) 중 하나
          example: SUCCESS
          in: query
          name: status
          schema:
            type: string
        - description: >-
            인용 출처 도메인 필터. 응답 sources[].domain 값이나 출처 통계의 domain 값을 그대로 넣습니다
            (eTLD+1·서브도메인 축 모두 매칭, 최대 253자)
          example: reddit.com
          in: query
          name: sourceDomain
          schema:
            type: string
        - description: >-
            인용 출처 URL 필터. 응답 sources[].url 값이나 URL 통계의 url 값을 그대로 넣습니다 (통계와 동일한
            정규화 축 매칭, 최대 2048자)
          example: https://en.wikipedia.org/wiki/Search_engine_optimization
          in: query
          name: sourceURL
          schema:
            type: string
        - description: 생성일 시작 (RFC3339)
          example: '2026-08-01T00:00:00Z'
          in: query
          name: from
          schema:
            type: string
        - description: 생성일 종료 (RFC3339)
          example: '2026-08-31T23:59:59Z'
          in: query
          name: to
          schema:
            type: string
        - description: 이전 응답의 nextCursor (첫 요청은 생략)
          example: eyJpZCI6NzIzMDF9
          in: query
          name: cursor
          schema:
            type: string
        - description: 페이지 크기 (기본 20, 최대 100)
          example: 20
          in: query
          name: limit
          schema:
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain.ListAnswersResponse'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain.ValidationError'
          description: limit 범위 위반(1~100), 지원하지 않는 status 값 (cursor·ID 형식 오류는 위 오류 표 참고)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain.UnauthorizedError'
          description: API 키 또는 액세스 토큰이 없거나 유효하지 않습니다
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain.InsufficientCreditsError'
          description: 조직 크레딧 잔액이 이 요청의 단가보다 적습니다
        '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.ListAnswersResponse:
      properties:
        answers:
          description: 답변 목록
          items:
            $ref: '#/components/schemas/domain.AnswerDTO'
          type: array
          uniqueItems: false
        nextCursor:
          description: 다음 페이지 cursor (더 이상 없으면 null)
          example: eyJpZCI6NzIzMDF9
          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.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.AnswerDTO:
      properties:
        content:
          description: 분류된 답변 본문 (status 가 SUCCESS 가 아니면 빈 문자열)
          example: >-
            AI 검색 노출을 늘리려면 먼저 어떤 질문에서 브랜드가 인용되는지 측정하고, 인용이 많은 출처 유형에 맞춰 콘텐츠를
            보강하는 순서로 접근합니다.
          type: string
        createdAt:
          description: 생성 일시 (RFC3339)
          example: '2026-08-05T02:24:50Z'
          type: string
        fanouts:
          description: AI가 답변 생성 시 수행한 검색 쿼리(query fan-out) 목록. 페이지네이션 없이 전체 제공
          example:
            - AI 검색 노출 최적화 방법
          items:
            type: string
          type: array
          uniqueItems: false
        id:
          description: >-
            답변 ID. 답변 단건 조회(GET /v1/platform/answers/{answerID})의 answerID 로
            사용합니다
          example: pv9LpgpbQyXpCAv8l0Lf0w
          type: string
        markdownURL:
          description: 답변 원본 마크다운(스크래핑 원문)의 파일 URL.
          example: https://cdn.trychainshift.ai/78af3dd2-0b10-4dc5-8c53-83fc875a625e.md
          type: string
        model:
          description: 이 답변을 수집한 모델
          example: NAVER_AI_BRIEFING
          type: string
        promptID:
          description: 답변 대상 프롬프트 ID. 프롬프트 조회(GET /v1/platform/prompts/{promptID})에 사용합니다
          example: KNUETdAfRhDY9lQTgu9wuw
          type: string
        query:
          description: 모델에 실제로 던진 질의 텍스트
          example: 우리 서비스가 AI 검색에 노출되게 하려면 어떻게 해야 하나요?
          type: string
        region:
          description: 이 답변을 수집한 지역 코드
          example: KR
          type: string
        runID:
          description: 이 답변을 생성한 프롬프트 실행 ID (실행 요청 시 발급). 연관된 프롬프트 실행이 없으면 생략
          example: S8cqDSjSot67bCK6YtmvHw
          type: string
        sources:
          description: 답변에 인용된 출처 목록. 페이지네이션 없이 전체 제공
          items:
            $ref: '#/components/schemas/domain.AnswerSourceDTO'
          type: array
          uniqueItems: false
        status:
          description: >-
            답변의 수집·분류 상태. PENDING: 아직 답변이 준비되지 않음(수집 또는 분류 진행 중, content 는 빈
            문자열),

            SUCCESS: 답변 분류까지 끝나 content 조회 가능, FAILED: 실패했거나 건너뜀(예: 모델이 AI 답변을
            내지 않은 경우).

            PENDING 에서 SUCCESS 또는 FAILED 로 한 번만 전이하며, 종료된 뒤에는 바뀌지 않습니다
          enum:
            - PENDING
            - SUCCESS
            - FAILED
          example: SUCCESS
          type: string
      required:
        - id
        - model
        - promptID
        - region
        - status
      type: object
    domain.AnswerSourceDTO:
      properties:
        domain:
          description: >-
            출처 도메인 (루트 도메인 기준). 출처 통계 API의 domain 필터에 그대로 넣을 수 있습니다. 판별하지 못한 경우
            생략됩니다
          example: wikipedia.org
          type: string
        title:
          description: 출처 콘텐츠 제목 (분류 전이면 빈 문자열)
          example: Search engine optimization
          type: string
        url:
          description: 출처 URL
          example: https://en.wikipedia.org/wiki/Search_engine_optimization
          type: string
      type: object
  securitySchemes:
    OrgAPIKeyAuth:
      description: '"조직 API 키를 입력하세요. 예: ''cs_live_xxxx''"'
      in: header
      name: API-Key
      type: apiKey

````