---
title: "List records"
method: POST
path: "/v2/objects/{object}/records/query"
tags: ["Records"]
---

# List records

`POST /v2/objects/{object}/records/query`

Lists people, company or other records, with the option to filter and sort results.

Required scopes: `record_permission:read`, `object_configuration:read`.

## Path parameters

- `object` string, required — A UUID or slug to identify the object to list records for.

## Request body

- object
  - `filter` object — An object used to filter results to a subset of results. Cannot be used together with `filter_view_id`. See the [full guide to filtering and sorting here](/rest-api/guides/filtering-and-sorting).
  - `filter_view_id` string, uuid — UUID of a saved view on this object or list. When set, results are filtered using that view's filter configuration. Cannot be used together with `filter`. Note: sorts, limits, and offsets are applied independently and are not taken from the view. All attributes are returned regardless of which attributes are visible in the view.
  - `sorts` union[] — An object used to sort results. See the [full guide to filtering and sorting here](/rest-api/guides/filtering-and-sorting).
    - union
      - object — Sort by attribute
        - `direction` 'asc' | 'desc', required — The direction to sort the results by.
        - `attribute` string, required — A slug or ID to identify the attribute to sort by.
        - `field` string — Which field on the value to sort by e.g. "last_name" on a name value.
      - object — Sort by path
        - `direction` 'asc' | 'desc', required — The direction to sort the results by.
        - `path` array[], required — You may use the `path` property to traverse record reference attributes and parent records on list entries. `path` accepts an array of tuples where the first element of each tuple is the slug or ID of a list/object, and the second element is the slug or ID of an attribute on that list/object. The first element of the first tuple must correspond to the list or object that you are querying. For example, if you wanted to sort by the name of the parent record (a company) on a list with the slug "sales", you would pass the value `[['sales', 'parent_record'], ['companies', 'name']]`.
          - union[]
            - union
              - …
        - `field` string — Which field on the value to sort by e.g. "last_name" on a name value.
  - `limit` number — The maximum number of results to return. Defaults to 500. See the [full guide to pagination here](/rest-api/guides/pagination).
  - `offset` number — The number of results to skip over before returning. Defaults to 0. See the [full guide to pagination here](/rest-api/guides/pagination).

## Response `200`

Success

- object — Success
  - `data` object[], required
    - `id` object, required
      - `workspace_id` string, uuid, required — A UUID identifying the workspace this record belongs to.
      - `object_id` string, uuid, required — A UUID identifying the object this record belongs to.
      - `record_id` string, uuid, required — A UUID identifying this record.
    - `created_at` string, required — When this record was created.
    - `web_url` string, uri, required — A URL that links directly to the record page in the Attio web application.
    - `values` object, required — A record type with an attribute `api_slug` as the key, and an array of value objects as the values.

## Other responses

- `400` — Bad Request
- `404` — Not Found

## Changes

> 16 revisions in range; 12 could not be searched.

- **2026-07-26** `0eb6da8a7a07` — 1 warning
  - added the new `IDR` enum value to the `data/items/values/additionalProperties/items/oneOf[subschema #3]/currency_code` response property for the response status `200`

[Change history](https://skmtc.dev/attio/apis/attio-api/changes/v2/objects/:object/records/query/post.md)

---

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