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

# Query records

> Returns one page of records matching every filter. Each record carries `id` and the
fields you asked for; with no `fields`, it carries the object's default fields.

To read the next page, send the same request again with `cursor` set to the previous
page's `pagination.nextCursor`. A cursor only works with the filters, sort and fields it
was issued under. `nextCursor` is null on the last page.

A `call` query returns only the calls the key's owner can open: see
`GET /v1/objects/call/{id}/transcript`.


> [!NOTE]
>
> The Clearskies API is in beta and available on request. To turn it on for your workspace, email
> [support@clearskies.cc](mailto:support@clearskies.cc).


## OpenAPI

````yaml api-reference/openapi.yaml POST /v1/objects/{object}/query
openapi: 3.1.0
info:
  title: Clearskies Public API
  version: '1'
  description: >
    Read the accounts, calls, contacts and deals in your Context Graph, and the
    transcripts of

    your calls, from your own code.


    Every response is a JSON envelope. A success carries `ok: true` and the
    result in `data`; a

    failure carries `ok: false` and an `error` whose `code` is the value to
    branch on. Both carry

    `requestId`, which support resolves a report against.


    The fields available can differ between workspaces, so read an object's
    schema with

    `GET /v1/objects/{object}` before you query it. The schema lists every field
    you can select,

    filter, sort, group or measure, and the filter operators each one accepts.
servers:
  - url: https://api.clearskies.cc
security:
  - apiKey: []
tags:
  - name: Objects
    description: The object types the API serves, and the fields each one carries.
  - name: Records
    description: Query and aggregate the records of one object type.
  - name: Calls
    description: Read what was said on a call.
paths:
  /v1/objects/{object}/query:
    post:
      tags:
        - Records
      summary: Query records
      description: >
        Returns one page of records matching every filter. Each record carries
        `id` and the

        fields you asked for; with no `fields`, it carries the object's default
        fields.


        To read the next page, send the same request again with `cursor` set to
        the previous

        page's `pagination.nextCursor`. A cursor only works with the filters,
        sort and fields it

        was issued under. `nextCursor` is null on the last page.


        A `call` query returns only the calls the key's owner can open: see

        `GET /v1/objects/call/{id}/transcript`.
      operationId: queryRecords
      parameters:
        - $ref: '#/components/parameters/object'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryRequest'
            example:
              filters:
                - field: amount
                  op: greaterThanOrEqual
                  value: 50000
                - field: closeDate
                  op: before
                  value: '2026-12-31'
              sort:
                - field: closeDate
                  direction: asc
              fields:
                - name
                - stage
                - amount
                - closeDate
                - account
              pageSize: 50
              includeTotalCount: true
      responses:
        '200':
          description: One page of records.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelope'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/RecordsPage'
              example:
                ok: true
                data:
                  records:
                    - id: 0198c7e2-51aa-7d41-b3f0-6e2a9c8d1f45
                      name: Acme renewal
                      stage: Negotiation
                      amount: 72000
                      closeDate: '2026-11-30'
                      account:
                        id: 0198c7e1-0f3b-7a52-8c6d-1b4e7f9a2c30
                        name: Acme
                  pagination:
                    nextCursor: eyJmaW5nZXJwcmludCI6Ii4uLiJ9
                    totalCount: 132
                requestId: 0199f2b0-7c41-7a3e-9d6c-2f5a1b8e4c07
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/TenantBlocked'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
components:
  parameters:
    object:
      name: object
      in: path
      required: true
      description: >-
        The object type. An unknown name is a `400`, and the message lists the
        valid ones.
      schema:
        $ref: '#/components/schemas/ObjectName'
  schemas:
    QueryRequest:
      type: object
      additionalProperties: false
      description: >
        Every member is optional, and a member sent as null counts as omitted.
        An empty body

        returns the first page of every record.
      properties:
        filters:
          type:
            - array
            - 'null'
          maxItems: 100
          items:
            $ref: '#/components/schemas/FilterClause'
        sort:
          type:
            - array
            - 'null'
          maxItems: 100
          items:
            $ref: '#/components/schemas/SortClause'
          description: Applied in order. Without it, records come in a fixed default order.
        fields:
          type:
            - array
            - 'null'
          maxItems: 100
          items:
            type: string
          description: >-
            The fields each record carries. Without it, records carry the
            object's default fields.
        pageSize:
          type:
            - integer
            - 'null'
          minimum: 0
          maximum: 100
          default: 25
          description: Records per page. 0 means the default.
        cursor:
          type:
            - string
            - 'null'
          description: >-
            The previous page's `pagination.nextCursor`. Omit it for the first
            page.
        includeTotalCount:
          type:
            - boolean
            - 'null'
          default: false
          description: Count every matching record. Only the first page carries the count.
    SuccessEnvelope:
      type: object
      required:
        - ok
        - data
        - requestId
      properties:
        ok:
          type: boolean
          const: true
        data: {}
        requestId:
          type: string
          description: Identifies this call. Quote it when you contact support.
        traceId:
          type: string
          description: Present on a traced request.
    RecordsPage:
      type: object
      required:
        - records
        - pagination
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/Record'
        pagination:
          $ref: '#/components/schemas/Pagination'
    ObjectName:
      type: string
      enum:
        - account
        - call
        - contact
        - deal
    FilterClause:
      type: object
      required:
        - field
        - op
      additionalProperties: false
      description: One condition. A request's filters must all match.
      properties:
        field:
          type: string
          description: A field whose `filterable` is true.
        op:
          allOf:
            - $ref: '#/components/schemas/FilterOperator'
          description: One of the field's `operators`.
        value:
          description: >
            Depends on `op`:


            - `isEmpty`, `isNotEmpty`: omit it, or send null.

            - `isIn`, `isNotIn`: an array of values.

            - Anything else: a single value.


            On a `referenceArray` field, `isIn` matches a record that refers to
            any of the ids,

            and `isNotIn` one that refers to none of them.


            Each value must match the field's type: a number for `integer`,
            `currency` and

            `duration`; `true` or `false` for `boolean`; an RFC 3339 timestamp

            (`2026-01-31T09:00:00Z`) or a date (`2026-01-31`) for `date` and
            `timestamp`; and a

            non-empty string for everything else, including a reference field's
            record `id`.

            Text comparisons ignore case.
          oneOf:
            - type: 'null'
            - type: string
            - type: number
            - type: boolean
            - type: array
              minItems: 1
              maxItems: 200
              items:
                oneOf:
                  - type: string
                  - type: number
                  - type: boolean
    SortClause:
      type: object
      required:
        - field
      additionalProperties: false
      properties:
        field:
          type: string
          description: A field whose `sortable` is true.
        direction:
          type: string
          enum:
            - asc
            - desc
          default: asc
          description: Records with no value for the field come last in either direction.
    Record:
      type: object
      required:
        - id
      description: >
        One record. Its other members are the fields you asked for, keyed by
        field name. Each

        value is written as its field's type dictates.
      properties:
        id:
          type: string
      additionalProperties:
        anyOf:
          - $ref: '#/components/schemas/TextValue'
          - $ref: '#/components/schemas/TextArrayValue'
          - $ref: '#/components/schemas/NumberValue'
          - $ref: '#/components/schemas/DateValue'
          - $ref: '#/components/schemas/TimestampValue'
          - $ref: '#/components/schemas/BooleanValue'
          - $ref: '#/components/schemas/ReferenceValue'
          - $ref: '#/components/schemas/ReferenceArrayValue'
          - $ref: '#/components/schemas/ExternalReferenceArrayValue'
    Pagination:
      type: object
      required:
        - nextCursor
      properties:
        nextCursor:
          type:
            - string
            - 'null'
          description: Pass it as `cursor` to read the next page. Null on the last page.
        totalCount:
          type: integer
          description: >-
            Every record the filters match. Present on the first page when
            `includeTotalCount` was set.
    ErrorEnvelope:
      type: object
      required:
        - ok
        - error
        - requestId
      properties:
        ok:
          type: boolean
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: >
                A diagnosis for a person to read. Its wording changes over time,
                so branch on

                `code`, not on this text.
        requestId:
          type: string
          description: Identifies this call. Quote it when you contact support.
        traceId:
          type: string
          description: Present on a traced request.
    FilterOperator:
      type: string
      enum:
        - equal
        - notEqual
        - contains
        - greaterThan
        - greaterThanOrEqual
        - lessThan
        - lessThanOrEqual
        - before
        - after
        - isIn
        - isNotIn
        - isEmpty
        - isNotEmpty
    TextValue:
      x-field-types:
        - text
        - slackText
      type:
        - string
        - 'null'
      description: >-
        The value of a `text` or `slackText` field. Null when the record has
        none.
    TextArrayValue:
      x-field-types:
        - textArray
      type:
        - array
        - 'null'
      items:
        type: string
      description: The value of a `textArray` field. Empty when the record has none.
    NumberValue:
      x-field-types:
        - integer
        - currency
        - duration
      type:
        - number
        - 'null'
      description: >-
        The value of an `integer`, `currency` or `duration` field. Null when the
        record has none.
    DateValue:
      x-field-types:
        - date
      type:
        - string
        - 'null'
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
      description: >-
        The value of a `date` field, as `YYYY-MM-DD`. Null when the record has
        none.
      example: '2026-11-30'
    TimestampValue:
      x-field-types:
        - timestamp
      type:
        - string
        - 'null'
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?Z$
      description: >-
        The value of a `timestamp` field, as an RFC 3339 timestamp in UTC. Null
        when the record has none.
      example: '2026-10-19T17:36:20.536789Z'
    BooleanValue:
      x-field-types:
        - boolean
      type:
        - boolean
        - 'null'
      description: The value of a `boolean` field. Null when the record has none.
    ReferenceValue:
      x-field-types:
        - reference
      type:
        - object
        - 'null'
      required:
        - id
      additionalProperties: false
      description: The value of a `reference` field. Null when the record points to none.
      properties:
        id:
          type: string
          description: The referenced record's `id`. Filter the field by this value.
        name:
          type:
            - string
            - 'null'
          description: >-
            The referenced record's name. Null when it has none, or no longer
            exists.
      example:
        id: 0198c7e1-0f3b-7a52-8c6d-1b4e7f9a2c30
        name: Acme
    ReferenceArrayValue:
      x-field-types:
        - referenceArray
      type:
        - array
        - 'null'
      items:
        $ref: '#/components/schemas/ReferenceValue'
      description: >-
        The value of a `referenceArray` field. Empty when the record refers to
        none.
    ExternalReferenceArrayValue:
      x-field-types:
        - externalReferenceArray
      type:
        - array
        - 'null'
      description: >
        The value of an `externalReferenceArray` field: the record's ids in the
        systems it came

        from. Empty when the record has none.
      items:
        type: object
        required:
          - id
          - system
        additionalProperties: false
        properties:
          id:
            type: string
            description: The record's id in that system.
          system:
            type: string
            description: The system the id belongs to, such as `salesforce` or `hubspot`.
      example:
        - id: 006XX0000012345
          system: salesforce
    ErrorCode:
      type: string
      description: The value to branch on when a request fails.
      enum:
        - BAD_REQUEST
        - UNAUTHORIZED
        - TENANT_BLOCKED
        - NOT_FOUND
        - RATE_LIMITED
        - INTERNAL_ERROR
        - SERVICE_UNAVAILABLE
        - GATEWAY_TIMEOUT
  headers:
    X-RateLimit-Limit:
      description: >
        Requests the key can make in a burst. The rate-limit headers are sent on
        the responses

        that list them, while the rate limiter is reachable.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current budget.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Seconds until the budget is full again.
      schema:
        type: integer
    X-Request-ID:
      description: >-
        Identifies this call, as `requestId` in the body does. Quote either to
        support.
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  responses:
    BadRequest:
      description: >
        The API declined to run the request. The message names the member at
        fault by its JSON

        path and lists what that member accepts. Fix the request rather than
        retrying it.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            ok: false
            error:
              code: BAD_REQUEST
              message: >-
                filters[0].op "contains" is not an operator "createdAt" accepts.
                Valid operators: equal, notEqual, before, after, isEmpty,
                isNotEmpty.
            requestId: 0199f2b0-7c41-7a3e-9d6c-2f5a1b8e4c07
    Unauthorized:
      description: >
        The key was not accepted: it is missing, malformed, unknown or revoked;
        the person who

        created it has been deactivated or has left the workspace; or the
        workspace is inactive.

        Every case answers the same way, so check each when a key that worked
        starts failing.
      headers:
        WWW-Authenticate:
          schema:
            type: string
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    TenantBlocked:
      description: The key's workspace is blocked.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: >
        The key has spent its request budget, or has too many requests in
        flight. Wait for

        `Retry-After` seconds, then retry.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InternalError:
      description: The request failed on our side. Quote `requestId` to support.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    ServiceUnavailable:
      description: >-
        The key could not be verified because a service it depends on did not
        answer. Retry.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    GatewayTimeout:
      description: >-
        The request ran past its deadline. Narrow the query with filters and
        retry.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >
        An API key created under Context Graph → API keys in the app sidebar,
        sent as `Authorization: Bearer csk_…`.

        The key is checked on every request, so a revoked key fails on its next
        call.

````

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