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

# Search Responses

> Find responses across your organization by an exact URL parameter value

Search matches one URL parameter and value in non-deleted studies in your API key's organization. Hidden responses are excluded unless `includeHidden=true`.

Results are newest first. Use `nextCursor` as `cursor` to fetch the next page, keeping `parameter`, `value`, `limit`, and `includeHidden` the same. A `null` cursor means there are no more results. The default `limit` is 100; the maximum is 1000.


## OpenAPI

````yaml api-v2/openapi.yaml GET /api/public/v1/responses
openapi: 3.0.3
info:
  title: Listen Labs Public API v2
  version: 2.0.0
  description: >-
    Create and launch studies, and retrieve response data programmatically.
    Authenticated with an `x-api-key` header; the key is scoped to a single
    organization.


    This spec is generated from the zod schemas in app/api/public/v1/_schema.ts
    (the ground truth for the contract) via `pnpm run generate-openapi`.
    Cross-field rules that JSON Schema cannot express (screening placement,
    min/maxSelect coupling, unique externalIds, reference resolution,
    exclusiveOption placement) are described on the relevant schemas and
    enforced by the server (returned as 400 responses).


    All error responses share one JSON envelope: `error` (human-readable
    message, may change) and `code` (stable machine-readable identifier; branch
    on this). 400 responses may also carry `issues` with per-field schema
    violations. The possible codes for each response are listed in its
    description.
servers:
  - url: https://listenlabs.ai
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /api/public/v1/responses:
    get:
      summary: Search workspace responses by URL parameter
      description: >-
        Searches responses in non-deleted studies in the API key's organization
        for an exact URL parameter value. Hidden responses are excluded unless
        includeHidden=true. Results are ordered by creation time, newest first.
        Keep the same query parameters when following nextCursor.
      operationId: searchResponses
      parameters:
        - name: parameter
          in: query
          required: true
          schema:
            type: string
            minLength: 1
        - name: value
          in: query
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: >-
            Use nextCursor from the previous page to continue. Keep the other
            search parameters unchanged. Invalid cursors return 400.
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
        - name: includeHidden
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Matching responses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponsesResponse'
              example:
                results:
                  - responseId: 877e4c64-6804-4bcb-a3d8-99805068f643
                    readableResponseId: 42
                    studyId: 5a2d7f20-eaf9-4f76-b885-d1f880779f44
                    linkId: customer-interviews
                    studyUrl: https://listenlabs.ai/p/customer-interviews
                    responseUrl: https://listenlabs.ai/p/customer-interviews/responses/42
                nextCursor: null
        '400':
          description: >-
            A required search parameter is missing or invalid. Codes:
            `bad_request`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                missingParameter:
                  value:
                    error: parameter is required
                    code: bad_request
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    SearchResponsesResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ResponseSearchResult'
        nextCursor:
          type: string
          nullable: true
      required:
        - results
        - nextCursor
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable description of the failure.
        code:
          type: string
          enum:
            - invalid_json
            - invalid_request_body
            - invalid_study_guide
            - wallet_required
            - insufficient_credits
            - bad_request
            - missing_api_key
            - invalid_api_key
            - unauthorized
            - launch_permission_denied
            - wallet_access_denied
            - forbidden
            - study_not_found
            - response_not_found
            - not_found
            - study_busy
            - concurrent_modification
            - conflict
            - internal_error
          description: >-
            Stable machine-readable error code. Branch on this, not on the
            `error` text, which may change.
      required:
        - error
        - code
      additionalProperties: false
    ResponseSearchResult:
      type: object
      properties:
        responseId:
          type: string
          format: uuid
        readableResponseId:
          type: integer
        studyId:
          type: string
          format: uuid
        linkId:
          type: string
        studyUrl:
          type: string
          format: uri
        responseUrl:
          type: string
          format: uri
      required:
        - responseId
        - readableResponseId
        - studyId
        - linkId
        - studyUrl
        - responseUrl
      additionalProperties: false
  responses:
    Unauthorized:
      description: 'Missing or invalid API key. Codes: `missing_api_key`, `invalid_api_key`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingApiKey:
              value:
                error: Missing x-api-key header
                code: missing_api_key
            invalidApiKey:
              value:
                error: Invalid API key
                code: invalid_api_key
    Forbidden:
      description: 'Key''s user not permitted for this resource. Codes: `forbidden`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            forbidden:
              value:
                error: API key user is not a member of the key's organization
                code: forbidden
    ServerError:
      description: >-
        Internal error (details are logged server-side, not returned). Codes:
        `internal_error`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            internalError:
              value:
                error: Internal server error
                code: internal_error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````