> ## Documentation Index > Fetch the complete documentation index at: https://developers.conveyour.com/llms.txt > Use this file to discover all available pages before exploring further. # List records > Returns a paginated list of records. Filter by object type using `obj_id` or `obj_name`. List records (supports pagination, search, sort, CSV export) **Permission:** Requires `manage_custom_objects`, `manage_custom_records` **or** `custom_objects`. Denials read `View Custom Records`. **Response shape:** `data` is an object with `count`, `page`, `pages`, `per_page`, `has_more`, `has_less` and `results`. `per_page` is honoured. ## OpenAPI ````yaml /api-reference/specs/custom-object-records.json get /api/custom/records openapi: 3.1.0 info: title: ConveYour API — Custom Object Records description: Create, retrieve, update, and delete records for your Custom Object types. version: 1.0.0 servers: - url: https://{subdomain}.conveyour.com description: Your organization's ConveYour instance variables: subdomain: default: acme description: >- Your organization's slug — the subdomain you sign in on. Replace `acme` with yours: if you sign in at `bigco.conveyour.com`, enter `bigco`. security: - conveyourToken: [] tags: - name: Custom Object Records description: Create, retrieve, update, and delete records for your Custom Object types. paths: /api/custom/records: get: tags: - Custom Object Records summary: List records description: >- Returns a paginated list of records. Filter by object type using `obj_id` or `obj_name`. List records (supports pagination, search, sort, CSV export) **Permission:** Requires `manage_custom_objects`, `manage_custom_records` **or** `custom_objects`. Denials read `View Custom Records`. **Response shape:** `data` is an object with `count`, `page`, `pages`, `per_page`, `has_more`, `has_less` and `results`. `per_page` is honoured. operationId: listRecordsSupportsPaginationSearchSortCsvExport parameters: - name: obj_id in: query description: >- Filter records by Custom Object type ID. Recommended to always pass this to scope results to the right object type. schema: type: string - name: obj_name in: query description: Alternative to `obj_id` — filter by object type name/slug. schema: type: string - name: search in: query description: Text search across record fields. schema: type: string - name: sort in: query description: >- Sort spec: `{ "field_name": 1 }` for ascending, `{ "field_name": -1 }` for descending. Pass plain `field_name` for custom data fields — the API adds the `d.` prefix automatically. Passing `d.field_name` will double-prefix the path. System fields (`created_at`, `updated_at`, `external_id`, etc.) are passed as-is. schema: type: object additionalProperties: true - name: page in: query description: >- Page number (1-based). When omitted or `0`, returns a flat array with no pagination. When set to `1` or higher, returns paginated results. Default: `0` (no pagination). schema: type: integer - name: per_page in: query description: >- Records per page when pagination is enabled (`page` ≥ 1). Default: `100`. schema: type: integer - name: format in: query description: Pass `csv` to download results as a CSV file instead of JSON. schema: type: string - $ref: '#/components/parameters/teams' responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: type: object properties: results: type: array items: $ref: '#/components/schemas/CustomRecord' page: type: integer description: Current page number. pages: type: integer description: Total number of pages. count: type: integer description: Total matching records across all pages. example: status: ok message: success data: - id: 64a1b2c3d4e5f6a7b8c9d0e1 obj_id: 64a1b2c3d4e5f6a7b8c9d0e2 external_id: vin-123 make: Ford model: F-150 year: 2022 '403': $ref: '#/components/responses/Forbidden' components: parameters: teams: name: teams[] in: query description: >- Team scope for the request, as one or more team ObjectIds. The brackets are required: PHP keeps only the last value for a repeated plain key, so `teams=A&teams=B` silently resolves to B alone. On requests with a JSON body you may send `teams` (no brackets) in the body instead. **Values that are not valid ObjectIds are silently ignored** — a mistyped team ID behaves as if no team was sent. See the [teams section of the API conventions guide](/guides/api-conventions#team-scoping). style: form explode: true schema: type: array items: type: string example: - 64a1b2c3d4e5f6a7b8c9d0ff schemas: Envelope: type: object description: The common response envelope shared by all ConveYour endpoints. properties: status: type: string enum: - ok - failed description: '`ok` on success, `failed` on error.' message: type: string description: Human-readable description of the result. data: description: >- The response payload — an object or an array depending on the endpoint. CustomRecord: type: object description: >- A custom object record. The field set varies per organization and per object: the parent object's stored schema is merged over the defaults. properties: id: type: string description: Record ID. obj_id: type: string description: Parent custom object. Required — the record is rejected without it. obj_name: type: string description: Parent object name. external_id: type: string description: Your identifier. Bulk upserts match on this. org_id: type: integer description: Owning organization. contact_id: type: string description: Linked contact, for non-standalone objects. created_at: type: integer description: Unix timestamp. updated_at: type: integer description: Unix timestamp. changed_at: type: integer description: Unix timestamp of the last value change. required: - obj_id additionalProperties: description: Any field defined on the parent custom object's schema. responses: Forbidden: description: >- The token is missing or invalid, or the service account behind it lacks the permission this endpoint requires. content: application/json: example: status: failed message: Lacking necessary permission add_contacts data: permission: add_contacts securitySchemes: conveyourToken: type: apiKey in: header name: x-conveyour-token description: >- Your API key token. Contacts endpoints require a **Server-only — Full API** key — see [Authentication](/quickstart). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.