> ## Documentation Index > Fetch the complete documentation index at: https://docs.custral.com/llms.txt > Use this file to discover all available pages before exploring further. # List records > List records in an object. Filter by property (`filter[key]=value`), `sort`, full-text `q` search, and offset **or** cursor pagination (follow `nextCursor`). **Requires scope:** `records:read`. ## OpenAPI ````yaml /openapi-v1.json get /v1/records/{object} openapi: 3.1.0 info: title: Custral API version: v1 description: >- The curated, versioned, API-key-authenticated public REST surface (`/v1`). Every endpoint here is what the official SDKs (`@custral/sdk`) and the MCP server are built on. Authenticate with a secret API key (`sk_…`) created in **Settings → Applications**. contact: name: Custral Support email: hello@custral.com url: https://custral.com license: name: Proprietary url: https://custral.com servers: - url: https://api.custral.com description: Production security: - ApiKey: [] tags: - name: Identity description: Introspect the calling API key. - name: Records description: Create, list, retrieve, and update records on any object. - name: Objects description: Read the object (table) schema of your workspace. - name: Conversations description: View, manage, and ingest conversations and their messages. - name: MCP description: Introspect the Model Context Protocol tool surface for a key. - name: Documents description: Read record notes / page documents as markdown. paths: /v1/records/{object}: get: tags: - Records summary: List records description: >- List records in an object. Filter by property (`filter[key]=value`), `sort`, full-text `q` search, and offset **or** cursor pagination (follow `nextCursor`). **Requires scope:** `records:read`. operationId: listRecords parameters: - name: object in: path required: true description: The object to list — its id, key, or name. schema: type: string example: contacts - name: limit in: query required: false description: Max records to return (1–200). Defaults to 50. schema: type: integer minimum: 1 maximum: 200 default: 50 - name: offset in: query required: false description: How many records to skip (offset pagination). Defaults to 0. schema: type: integer minimum: 0 default: 0 - name: filter in: query required: false style: deepObject explode: true description: >- Filter by property: `filter[key]=value` (exact) or `filter[key][op]=value` (op ∈ eq/neq/gt/lt/gte/lte/contains/notContains/startsWith/endsWith/empty/notEmpty). Multiple properties AND together. schema: type: object additionalProperties: true - name: sort in: query required: false description: >- Sort by a property key (or `created_at`/`updated_at`), e.g. `amount:desc`. schema: type: string - name: q in: query required: false description: >- Full-text search. Relevance-ranked; ignores filter/sort/cursor when set. schema: type: string - name: cursor in: query required: false description: >- Pagination token from a previous response cursor. Mutually exclusive with offset. schema: type: string responses: '200': description: A page of records. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/RecordList' reqId: $ref: '#/components/schemas/RequestId' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: schemas: RecordList: type: object description: A page of records. properties: data: type: array items: $ref: '#/components/schemas/Record' total: type: - integer - 'null' description: Total matching records, or null. example: 128 limit: type: integer offset: type: integer nextCursor: type: - string - 'null' description: Cursor token for the next page, or null at the end. prevCursor: type: - string - 'null' description: Cursor token for the previous page, or null at the start. required: - data RequestId: type: string description: >- A per-request id (`req_…`). Quote it to support when reporting a problem. example: req_2a1f9c8e7b6d5 Record: type: object description: >- A record on an object. The concrete fields depend on the object's schema. additionalProperties: true properties: id: type: string example: rec_123 name: type: - string - 'null' example: Jane Doe objectId: type: string example: obj_123 required: - id Error: type: object description: >- The failure envelope. Every error carries a machine-readable `code` and the `reqId` of the failing request. properties: error: type: object properties: code: type: string example: insufficient_scope required: - code reqId: $ref: '#/components/schemas/RequestId' required: - error responses: Unauthorized: description: >- The API key is missing, unknown, inactive, or expired (`code: invalid_api_key`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key reqId: req_2a1f9c8e7b6d5 Forbidden: description: >- The key lacks the scope this endpoint requires (`code: insufficient_scope`). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: insufficient_scope reqId: req_2a1f9c8e7b6d5 NotFound: description: 'The object or record was not found (`code: not_found`).' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found reqId: req_2a1f9c8e7b6d5 securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: sk_... description: >- A Custral **secret** API key (`sk_…`), created in Settings → Applications. Sent as `Authorization: Bearer sk_…`. The `X-Api-Key: sk_…` header is also accepted and takes precedence. Never expose a secret key in a browser. ```` ## Related topics - [The Record object](/dev/api-reference/records.md) - [Voice & Calls](/comms/voice/overview.md) - [Lists](/data/collections/overview.md) - [List](/blocks/embedded/databases/list.md) - [Smart lists](/data/collections/queue.md)