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

# Query records

> Search for records across a folder or space (index-backed). At least one of `folder` or `space_id` must be provided, and a Bearer JWT is required (used to derive the tenant) — an API key alone is rejected on this endpoint. `folder`/`space_id` conditions are ANDed. Results are sorted by `created_at`.



## OpenAPI

````yaml /api-reference/endpoint/records/openapi.json get /records
openapi: 3.1.0
info:
  title: Records API
  version: 1.1.0
  description: >-
    Record configurations (schemas, views, versions) and the records that
    conform to them. Record IDs are server-generated, config IDs are
    client-supplied (`^[a-zA-Z0-9_-]+$`). Configs and records are updated with
    PUT: a config update applies only the fields sent, a record update merges
    `data`. Editing a config schema does not retroactively re-validate existing
    records. Publish a config version to snapshot the stored config; list and
    read versions to see its history.
servers:
  - url: https://api.quiva.ai
    description: Production API server
security:
  - bearerAuth: []
  - apiKeyAuth: []
tags:
  - name: Record Configs
    description: >-
      Manage record configuration schemas. Each configuration defines the
      structure (fields, types, validation rules) that records must conform to.
  - name: Records
    description: >-
      Manage individual data records. Each record belongs to exactly one
      configuration and its data is validated against that configuration's
      schema.
  - name: Record Config Collections
    description: Groups of record configs.
  - name: Record Config Versions
    description: Published snapshots of a record config.
  - name: Record History
    description: The change history of a record.
  - name: Record Assessment
  - name: Strategy and Simulation
  - name: Record Metrics
paths:
  /records:
    get:
      tags:
        - Records
      summary: Query records
      description: >-
        Search for records across a folder or space (index-backed). At least one
        of `folder` or `space_id` must be provided, and a Bearer JWT is required
        (used to derive the tenant) — an API key alone is rejected on this
        endpoint. `folder`/`space_id` conditions are ANDed. Results are sorted
        by `created_at`.
      operationId: queryRecords
      parameters:
        - name: folder
          in: query
          required: false
          description: >-
            Folder ID to filter records by. At least one of `folder` or
            `space_id` must be provided.
          schema:
            type: string
        - name: space_id
          in: query
          required: false
          description: >-
            Space ID to filter records by. At least one of `folder` or
            `space_id` must be provided.
          schema:
            type: string
        - name: config_id
          in: query
          required: false
          description: >-
            Comma-separated config IDs to narrow the query. One ID is ANDed with
            the folder/space filter; multiple IDs form an OR group.
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum number of records to return.
          schema:
            type: integer
        - name: offset
          in: query
          required: false
          description: >-
            Number of records to skip (pagination). At most 10,000; use `cursor`
            to read further.
          schema:
            type: integer
        - name: cursor
          in: query
          required: false
          description: >-
            `next_cursor` from the previous page, passed back unchanged with the
            same filter and sort_by. Replaces offset: sending both is refused
            400, as is a cursor with latest_by. Pages of any depth; rows with
            equal sort values are neither skipped nor repeated. The sort field
            must be a declared sortable index field. Answers 501 while the
            indexer predates cursor paging.
          schema:
            type: string
        - name: want_cursor
          in: query
          required: false
          description: >-
            `true` on the first page of a cursor walk: the reply then carries
            `next_cursor` and no `next_offset`. Cursor pages order by the
            index's sort keys; without it the page is ordered and paged exactly
            as before. Refused 400 with latest_by; answers 501 while the indexer
            predates cursor paging.
          schema:
            type: boolean
        - name: parent_folder
          in: query
          required: false
          description: Records whose parent_folder equals this; ANDed with folder.
          schema:
            type: string
        - name: scope_folder
          in: query
          required: false
          description: >-
            Records whose folder OR parent_folder equals this. Satisfies the
            scope requirement on its own.
          schema:
            type: string
        - name: under_folder
          in: query
          required: false
          description: >-
            Records in this folder or anywhere below it, at any depth: a folder,
            or a dotted folder path (read by its last parent.child pair). One
            indexed term, ANDed with every other parameter. Echoed as
            under_folder in the reply. Answers 503 until the account's records
            are indexed with their folder ancestors. Satisfies the scope
            requirement on its own.
          schema:
            type: string
        - name: ancestors_unverified
          in: query
          required: false
          description: >-
            Staff only, with under_folder: answer before the account's marker is
            set, so the backfill can check parity. A client is refused 403.
          schema:
            type: boolean
        - name: filter
          in: query
          required: false
          description: JSON `{conditions, sort_by}` over record and declared index_fields.
          schema:
            type: string
        - name: sort_by
          in: query
          required: false
          description: Field name; prefix `-` for descending. Default `created_at`.
          schema:
            type: string
        - name: fields
          in: query
          required: false
          description: Comma-separated payload paths to keep.
          schema:
            type: string
        - name: search
          in: query
          required: false
          description: >-
            Words ANDed; each matches any search field (text by prefix, keyword
            exactly). Needs one config_id.
          schema:
            type: string
        - name: search_fields
          in: query
          required: false
          description: >-
            Comma-separated declared text or keyword index fields; defaults to
            every declared text field.
          schema:
            type: string
        - name: date_field
          in: query
          required: false
          description: '`created_at`, `updated_at` or a declared date index field.'
          schema:
            type: string
        - name: date_from
          in: query
          required: false
          description: Inclusive lower bound, RFC3339 or YYYY-MM-DD.
          schema:
            type: string
        - name: date_to
          in: query
          required: false
          description: >-
            Inclusive upper bound, RFC3339 or YYYY-MM-DD (a bare date covers its
            whole day).
          schema:
            type: string
        - name: latest_by
          in: query
          required: false
          description: >-
            JSON `{"group_field":"...","order_field":"..."}`: keep the row with
            the highest order_field per group_field value. order_field must be a
            declared sortable index field. Reads one page of at most 1000 scoped
            rows, highest order_field first (the index page maximum; no sortable
            record field is unique, so deeper paging is not used); the reply
            carries `truncated: true` when more matched. total_hits counts
            groups.
          schema:
            type: string
      responses:
        '200':
          description: Matching records
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Response'
                  - properties:
                      body:
                        $ref: '#/components/schemas/RecordList'
        '400':
          description: Missing required filter parameter or invalid authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No records found matching the query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Response:
      type: object
      properties:
        status_code:
          type: integer
          description: HTTP status code echoed in the response body.
        body:
          type: object
          description: Response payload.
    RecordList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Record'
        results_total:
          type: integer
          description: Number of records returned in this response.
        total_hits:
          type: integer
          description: >-
            Total matching records across all pages (returned by the query
            endpoint; used with limit/offset).
        next_cursor:
          type: string
          description: >-
            Query endpoint, with `want_cursor` or `cursor`: pass as `cursor` for
            the next page. Absent on the last page. It resumes after the last
            record returned, so a page trimmed to fit the reply, or with records
            withheld from a client, loses nothing.
    ErrorResponse:
      type: object
      properties:
        status_code:
          type: integer
        body:
          type: object
          properties:
            error:
              type: string
              description: Human-readable error message.
      example:
        status_code: 400
        body:
          error: field 'rating' is required
    Record:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier. Auto-generated if not provided on creation.
        config_id:
          type: string
          description: ID of the RecordConfig that defines this record's schema.
        data:
          type: object
          additionalProperties: true
          description: >-
            Key-value map of field values. Keys correspond to SchemaField IDs.
            Values must match the field type defined in the schema. Extra keys
            not defined in the schema are permitted.
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: ISO 8601 timestamp set automatically on creation.
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: ISO 8601 timestamp updated automatically on every modification.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

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