> ## Documentation Index
> Fetch the complete documentation index at: https://dev-docs.trychainshift.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List answers

> Lists the answers obtained by running prompts. Each answer includes the body along with sources, fan-outs (fanouts), and the original markdown (markdownURL). PENDING and FAILED runs are also returned with their status.

`markdownURL` is always included for answers whose `status` is `SUCCESS`. It is omitted only for answers not yet collected (`PENDING`) or whose collection failed (`FAILED`), since they have no original content, so you do not need to handle a missing value when working with `SUCCESS` answers.

### Errors

| HTTP | Code | Description |
| --- | --- | --- |
| 400 | `COMMON_VALIDATION` | • limit out of range (1 to 100) • Unsupported status value |
| 400 | `COMMON_INVALID_CURSOR` | Invalid cursor format |
| 400 | `COMMON_BINDING` | Invalid runID, promptSetID, or promptID format (`PLATFORM_INVALID_ID` in details) |
| 401 | `COMMON_UNAUTHORIZED` | API key or access token is missing or invalid |
| 402 | `INSUFFICIENT_CREDITS` | Organization credit balance is lower than the unit price of this request |
| 429 | `PLATFORM_RATE_LIMIT_EXCEEDED` | Rate limit exceeded. Wait for the number of seconds in the `Retry-After` header, then retry |
| 500 | — | Internal server error. Returns `message` and `requestID` without `code` |

For the meaning of the response fields and the empty-value rules (when `fanouts` and `sources` are empty), see [Answer object](https://dev-docs.trychainshift.ai/en/api-reference/answers/answer-object.md). For real response examples and interpretation, see the [Retrieving answers](https://dev-docs.trychainshift.ai/en/guides/collecting-answers.md) guide.


## OpenAPI

````yaml openapi.en.json GET /v1/platform/answers
openapi: 3.1.0
info:
  description: >-
    Platform API for external partners. Uses organization API key based
    authentication.

    ### Common request limits

    - The request body size is limited to 2MiB. Exceeding it returns 413 with
    the `COMMON_REQUEST_BODY_TOO_LARGE` code.

    - Array parameters and string fields have per-endpoint count and length
    limits. The limits are stated in each field or parameter description, and
    violating them returns 400 with the `COMMON_VALIDATION` code.

    ### Error responses

    The error response body always has the same three fields regardless of the
    status code.

    | Field | Type | Meaning |

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

    | `code` | string | A fixed identifier for the error type. This is the only
    value clients should branch on. The codes each endpoint returns are listed
    in the "Errors" table of that API. |

    | `message` | string | A human-readable, one-line summary of the whole
    error. There is always exactly one. |

    | `details` | array of strings | Individual reasons that do not fit in the
    single `message` line. Even a single reason is returned as an array of
    length 1, and the field is omitted when there is nothing to include. |

    - `details` is an array in every error. It is never returned as a string or
    an object, so no type-based branching is needed.

    - The wording of `details` is not a fixed contract. Use it only for display
    and debugging, and do not parse the strings to branch. Branch on `code`
    instead.

    - `details` is the only field that carries multiple reasons. There is no
    `messages` field in the response.

    - On validation failure (`COMMON_VALIDATION`), `details` contains one
    `"field: reason"` line per violated field. Example:
    `{"code":"COMMON_VALIDATION","message":"Data validation
    failed","details":["keywords: up to 100 items can be entered"]}`

    - `message` defaults to Korean and is returned in English when you send
    `Accept-Language: en`. `details` follows the same rule when it carries
    per-field reasons such as validation failures, but errors that include raw
    text for diagnostic purposes may contain wording in a language other than
    the requested one.

    - Only 500 has a different shape. It returns `message` and a `requestID` to
    reference when contacting support, without `code`.
  title: Platform API
  version: '1.0'
servers:
  - url: http://dev-platform-api.trychainshift.ai/api
security: []
tags:
  - description: >-
      The top-level account unit that API keys belong to. Retrieve the
      organization's basic information.
    name: Organization
  - description: >-
      A target brand whose exposure in AI services is monitored. Provides brand
      registration, retrieval, update, and deletion.
    name: Brand
  - description: >-
      Keyword intelligence for analyzing brands and markets. Provides Google and
      Naver search metrics, related and autocomplete keyword lookups, and site
      URL based keyword analysis.
    name: Keyword (Beta)
  - description: >-
      A group that organizes prompts by purpose. Provides create, get, update,
      and delete operations for prompt sets.
    name: PromptSet
  - description: >-
      A sentence-level unit of a query sent to an AI service. Provides prompt
      create, get, update, and delete, plus bulk creation.
    name: Prompt
  - description: AI service models used for prompt runs. Lists the supported models.
    name: Model
  - description: The region used to run prompts. Retrieves the list of supported regions.
    name: Region
  - description: >-
      The unit of work that actually runs prompts against AI services. Provides
      prompt run requests and retrieval of progress status and lists.
    name: Run
  - description: >-
      An AI service response collected by a run. Retrieves answers including
      sources and search queries.
    name: Answer
  - description: >-
      Statistics on the sources cited in answers, at the domain and URL level.
      Retrieve the citation summary and per-domain and per-URL citation
      statistics.
    name: SourceStatistics (Beta)
  - description: >-
      Statistics on tokens (Kiwi nouns) in answer bodies. Retrieves a ranking of
      the most frequent tokens and the tokens near a specific word.
    name: AnswerStatistics (Beta)
  - description: >-
      Statistics on the search queries (fan-outs) the AI actually issued while
      generating answers. Retrieves a ranking of search queries by occurrence
      count.
    name: FanoutStatistics (Beta)
  - description: >-
      An auxiliary feature that identifies proper nouns in text. Provides proper
      noun extraction.
    name: ProperNoun (Beta)
  - description: >-
      Organization credit balance and Platform API billing information.
      Retrieves the current credit balance.
    name: Credit
externalDocs:
  description: ''
  url: ''
paths:
  /v1/platform/answers:
    get:
      tags:
        - Answer
      summary: List answers
      description: >-
        Lists the answers obtained by running prompts. Each answer includes the
        body along with sources, fan-outs (fanouts), and the original markdown
        (markdownURL). PENDING and FAILED runs are also returned with their
        status.


        `markdownURL` is always included for answers whose `status` is
        `SUCCESS`. It is omitted only for answers not yet collected (`PENDING`)
        or whose collection failed (`FAILED`), since they have no original
        content, so you do not need to handle a missing value when working with
        `SUCCESS` answers.


        ### Errors


        | HTTP | Code | Description |

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

        | 400 | `COMMON_VALIDATION` | • limit out of range (1 to 100) •
        Unsupported status value |

        | 400 | `COMMON_INVALID_CURSOR` | Invalid cursor format |

        | 400 | `COMMON_BINDING` | Invalid runID, promptSetID, or promptID
        format (`PLATFORM_INVALID_ID` in details) |

        | 401 | `COMMON_UNAUTHORIZED` | API key or access token is missing or
        invalid |

        | 402 | `INSUFFICIENT_CREDITS` | Organization credit balance is lower
        than the unit price of this request |

        | 429 | `PLATFORM_RATE_LIMIT_EXCEEDED` | Rate limit exceeded. Wait for
        the number of seconds in the `Retry-After` header, then retry |

        | 500 | — | Internal server error. Returns `message` and `requestID`
        without `code` |
      operationId: listAnswers
      parameters:
        - description: >-
            Filter to narrow the scope to a specific prompt run (the ID issued
            when the run was requested)
          example: S8cqDSjSot67bCK6YtmvHw
          in: query
          name: runID
          schema:
            type: string
        - description: >-
            Filter to narrow the scope to a specific prompt set (the id from the
            set list or create response)
          example: IkVMHhjFWcBXcJ41-h9yBQ
          in: query
          name: promptSetID
          schema:
            type: string
        - description: >-
            Filter to narrow the scope to a specific prompt (the id from the
            prompt list or create response)
          example: KNUETdAfRhDY9lQTgu9wuw
          in: query
          name: promptID
          schema:
            type: string
        - description: Filter that narrows the scope to a specific model
          example: CHATGPT
          in: query
          name: model
          schema:
            type: string
        - description: Filter to narrow the scope to a specific region
          example: KR
          in: query
          name: region
          schema:
            type: string
        - description: >-
            Filter that narrows the scope to a specific location (city-level,
            below country). The code value from GET /locations
          example: US-NEW_YORK
          in: query
          name: location
          schema:
            type: string
        - description: >-
            Collection and classification status filter. One of PENDING (answer
            not ready yet), SUCCESS (answer classification finished), FAILED
            (failed or skipped)
          example: SUCCESS
          in: query
          name: status
          schema:
            type: string
        - description: >-
            Source domain filter. Enter the sources[].domain value from the
            response or the domain value from source statistics as is (matches
            both the eTLD+1 and subdomain axes, up to 253 characters)
          example: reddit.com
          in: query
          name: sourceDomain
          schema:
            type: string
        - description: >-
            Cited source URL filter. Pass the sources[].url value from the
            response or the url value from URL statistics as is (matched on the
            same normalization axis as statistics, up to 2048 characters)
          example: https://en.wikipedia.org/wiki/Search_engine_optimization
          in: query
          name: sourceURL
          schema:
            type: string
        - description: Created date start (RFC3339)
          example: '2026-08-01T00:00:00Z'
          in: query
          name: from
          schema:
            type: string
        - description: Creation date end (RFC3339)
          example: '2026-08-31T23:59:59Z'
          in: query
          name: to
          schema:
            type: string
        - description: nextCursor from the previous response (omit on the first request)
          example: eyJpZCI6NzIzMDF9
          in: query
          name: cursor
          schema:
            type: string
        - description: Page size (default 20, max 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 out of range (1 to 100), unsupported status value (for cursor
            and ID format errors, see the error table above)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain.UnauthorizedError'
          description: API key or access token is missing or invalid
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain.InsufficientCreditsError'
          description: >-
            The organization's credit balance is lower than the unit price of
            this request
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain.RateLimitExceededError'
          description: >-
            Rate limit exceeded. Wait the number of seconds in the Retry-After
            header, then retry
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/domain.InternalServerError'
          description: >-
            Internal server error. Include the requestID in your report so it
            can be traced
      security:
        - OrgAPIKeyAuth: []
components:
  schemas:
    domain.ListAnswersResponse:
      properties:
        answers:
          description: Answer list
          items:
            $ref: '#/components/schemas/domain.AnswerDTO'
          type: array
          uniqueItems: false
        nextCursor:
          description: Cursor for the next page (null if there are no more)
          example: eyJpZCI6NzIzMDF9
          type: string
      type: object
    domain.ValidationError:
      properties:
        code:
          description: Error code
          example: COMMON_VALIDATION
          type: string
        details:
          description: 'List of reasons per violating field (one "field: reason" per line)'
          example:
            - 'limit: must be 100 or less'
          items:
            type: string
          type: array
          uniqueItems: false
        message:
          description: >-
            Error message (Korean by default, English when Accept-Language: en
            is specified)
          example: Data validation failed
          type: string
      type: object
    domain.UnauthorizedError:
      properties:
        code:
          description: Error code
          example: COMMON_UNAUTHORIZED
          type: string
        message:
          description: >-
            Error message (Korean by default, English when Accept-Language: en
            is specified)
          example: Unauthenticated user
          type: string
      type: object
    domain.InsufficientCreditsError:
      properties:
        code:
          description: Error code
          example: INSUFFICIENT_CREDITS
          type: string
        message:
          description: >-
            Error message (Korean by default, English when Accept-Language: en
            is specified)
          example: Insufficient credits.
          type: string
      type: object
    domain.RateLimitExceededError:
      properties:
        code:
          description: Error code
          example: PLATFORM_RATE_LIMIT_EXCEEDED
          type: string
        message:
          description: >-
            Error message (Korean by default, English when Accept-Language: en
            is specified)
          example: Too many requests. Please try again later.
          type: string
      type: object
    domain.InternalServerError:
      properties:
        message:
          description: Error message (not localized)
          example: Internal Server Error
          type: string
        requestID:
          description: >-
            Request identifier to reference in support inquiries (same value as
            the X-Request-Id response header)
          example: bkZqnHQepkgTOocTvyHWSlHcGzRqQbZk
          type: string
      type: object
    domain.AnswerDTO:
      properties:
        content:
          description: Classified answer body (empty string unless status is SUCCESS)
          example: >-
            To increase AI search visibility, first measure which questions your
            brand is cited in, then strengthen your content to match the source
            types that are cited most often.
          type: string
        createdAt:
          description: Creation time (RFC3339)
          example: '2026-08-05T02:24:50Z'
          type: string
        fanouts:
          description: >-
            List of search queries (query fan-out) the AI performed while
            generating the answer. Provided in full without pagination
          example:
            - How to optimize AI search visibility
          items:
            type: string
          type: array
          uniqueItems: false
        id:
          description: >-
            Answer ID. Used as the answerID when getting a single answer (GET
            /v1/platform/answers/{answerID})
          example: pv9LpgpbQyXpCAv8l0Lf0w
          type: string
        location:
          description: >-
            Code of the location (city-level, below country) where this answer
            was collected. null if location was not specified at submission and
            the answer was collected at the region level
          example: US-NEW_YORK
          type: string
        markdownURL:
          description: File URL of the original answer markdown (raw scraped text).
          example: https://cdn.trychainshift.ai/78af3dd2-0b10-4dc5-8c53-83fc875a625e.md
          type: string
        model:
          description: Model that collected this answer
          example: NAVER_AI_BRIEFING
          type: string
        promptID:
          description: >-
            ID of the prompt this answer is for. Used when getting the prompt
            (GET /v1/platform/prompts/{promptID})
          example: KNUETdAfRhDY9lQTgu9wuw
          type: string
        query:
          description: The query text actually sent to the model
          example: How can we get our service to appear in AI search?
          type: string
        region:
          description: Code of the region where this answer was collected
          example: KR
          type: string
        runID:
          description: >-
            ID of the prompt run that produced this answer (issued when the run
            request was made). Omitted if there is no associated prompt run
          example: S8cqDSjSot67bCK6YtmvHw
          type: string
        sources:
          description: >-
            List of sources cited in the answer. Provided in full without
            pagination
          items:
            $ref: '#/components/schemas/domain.AnswerSourceDTO'
          type: array
          uniqueItems: false
        status:
          description: >-
            Collection and classification status of the answer. PENDING: the
            answer is not ready yet (collection or classification in progress,
            content is an empty string),

            SUCCESS: classification is finished and content is available,
            FAILED: failed or skipped (for example, the model did not produce an
            AI answer).

            Transitions only once from PENDING to SUCCESS or FAILED and does not
            change after it ends
          enum:
            - PENDING
            - SUCCESS
            - FAILED
          example: SUCCESS
          type: string
      required:
        - id
        - model
        - promptID
        - region
        - status
      type: object
    domain.AnswerSourceDTO:
      properties:
        domain:
          description: >-
            Source domain (root domain). You can pass it as is to the domain
            filter of the source statistics API. Omitted if it could not be
            determined
          example: wikipedia.org
          type: string
        title:
          description: Source content title (empty string if not yet classified)
          example: Search engine optimization
          type: string
        url:
          description: Source URL
          example: https://en.wikipedia.org/wiki/Search_engine_optimization
          type: string
      type: object
  securitySchemes:
    OrgAPIKeyAuth:
      description: '"Enter your organization API key. Example: ''cs_live_xxxx''"'
      in: header
      name: API-Key
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.