---
title: "Query (v3)"
method: POST
path: "/api/v3/query"
---

# Query (v3)

`POST /api/v3/query`

Search, filter, sort, aggregate, and paginate records from any object using a structured JSON body.

## Request body

- object
  - `objectType` integer, required — The numeric object type code to query.
  - `fields` object[], required — The fields to include in the response. At least one field must be specified.
    - `name` string, required — A valid field name. Use an underscore to reference related fields (e.g. `contactid_fullname`).
    - `alias` string — An alias for the aggregated field in the result set. Only used when `aggrFunc` is specified; ignored otherwise. Defaults to the field name.
    - `aggrFunc` 'SUM' | 'COUNT' | 'MIN' | 'MAX' — Aggregate function to apply to the field. Requires `groupBy` to be specified at the top level; returns an error otherwise.
  - `filter` object[] — An array of condition groups. Groups are joined with AND logic between them.
    - `type` 'AND' | 'OR', required — The logical operator applied between conditions in this group.
    - `conditions` object[], required — An array of filter conditions.
      - `fieldName` string, required — The field name to filter on. Supports related fields (e.g. `ownerid_createdby`).
      - `operator` 'eq' | 'ne' | 'lt' | 'gt' | 'le' | 'ge' | 'start-with' | 'not-start-with' | 'is-null' | 'is-not-null' | 'eq-in' | 'not-in' | 'between' | 'userid', required — The comparison operator.
      - `value` union — The value to compare against. Type depends on the operator: omit for `is-null`, `is-not-null`, `userid`; use an array for `eq-in`, `not-in`, `between`; use a single value for all others. Date fields also accept relative values like `today`, `this-week`, etc.
        - string
        - number
        - boolean
        - union[]
          - union
            - string
            - number
  - `orderBy` object[] — Fields to sort results by. When `groupBy` is present, all orderBy fields must also appear in the groupBy array.
    - `name` string, required — A valid field name. Supports related fields.
    - `order` 'asc' | 'desc' — Sort direction.
  - `groupBy` object[] — Fields to group results by. Required when using aggregation functions.
    - `name` string, required — A valid field name. Supports related fields.
    - `datePeriod` 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR' | 'HOUR_PART' | 'DAY_PART' | 'WEEK_PART' | 'MONTH_PART' | 'QUARTER_PART' | 'DAY_OF_WEEK' — Date/DateTime field into a time period. EXACT (HOUR/DAY/WEEK/MONTH/QUARTER/YEAR) place each record in a unique slot on the timeline. Recurring (*_PART, DAY_OF_WEEK) collapse records across years/months into the same slot. Only valid on Date or DateTime fields.
  - `pageNumber` integer — The page number to return.
  - `pageSize` integer — The number of records per page.

## Response `200`

200

- object
  - `data` object[] — Array of matching records. Each record includes an `_id` field with the primary key.
  - `success` boolean
  - `message` string
  - `pageNumber` integer
  - `pageSize` integer
  - `isLastPage` boolean — When true, there are no more pages of results.

## Other responses

- `400` — 400
- `403` — 403

---

[API](https://skmtc.dev/fireberry/apis/fireberry-api.md) · [All operations](https://skmtc.dev/fireberry/apis/fireberry-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fireberry/fireberry-api/revisions/ad6720f3920f/schema)