> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List entity records by cursor
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Returns one page of the records in one of the app's entities, with a cursor for the next page instead of `skip`. Deleted records are left out.
Use it for exports, sync jobs, and any loop over a large entity. Every page costs the same however far in you are, and records deleted between pages don't shift where the next page starts.
Filter and choose fields the same way as [List entity records](/api-reference/list-entity-records), including by passing a field name directly as a query parameter. For the next page, pass `next_cursor` from the response as `cursor`. The cursor carries the filter, sort, and fields, so you don't need to repeat them, and repeating one with a different value is rejected. Stop when `has_more` is `false`. Every page holds `limit` records except the last. A cursor only works for the user it was issued to, on the same app and entity.
Records come back newest first unless you set `sort`. Records with no value in the sort field come first in ascending order and last in descending order. Records that share the same sort value are each returned once. A record whose stored value in the sort field isn't the type the entity's schema declares is left out.
With `distinct`, `items` holds the distinct values of that field among the matching records instead of records, in ascending order and without `null`. Each element of an array field counts as a value. `sort` and `fields` can't be combined with it, `limit` goes up to 1000, and an entity with field-level read rules doesn't support it.
Row-level security applies, so you only get the records the entity's `rls` read rule lets your credential see. The `User` entity isn't supported. Use [List app users](/api-reference/list-app-users) instead.
This endpoint accepts a personal API key belonging to a user with access to the app, including a read-only key. Workspace API keys are not accepted.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json get /api/apps/{app_id}/entities/{entity_name}/v2/list
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- PersonalAccessTokenAuth: []
paths:
/api/apps/{app_id}/entities/{entity_name}/v2/list:
get:
summary: List entity records by cursor
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Returns one page of the records in one of the app's entities, with a
cursor for the next page instead of `skip`. Deleted records are left
out.
Use it for exports, sync jobs, and any loop over a large entity. Every
page costs the same however far in you are, and records deleted between
pages don't shift where the next page starts.
Filter and choose fields the same way as [List entity
records](/api-reference/list-entity-records), including by passing a
field name directly as a query parameter. For the next page, pass
`next_cursor` from the response as `cursor`. The cursor carries the
filter, sort, and fields, so you don't need to repeat them, and
repeating one with a different value is rejected. Stop when `has_more`
is `false`. Every page holds `limit` records except the last. A cursor
only works for the user it was issued to, on the same app and entity.
Records come back newest first unless you set `sort`. Records with no
value in the sort field come first in ascending order and last in
descending order. Records that share the same sort value are each
returned once. A record whose stored value in the sort field isn't the
type the entity's schema declares is left out.
With `distinct`, `items` holds the distinct values of that field among
the matching records instead of records, in ascending order and without
`null`. Each element of an array field counts as a value. `sort` and
`fields` can't be combined with it, `limit` goes up to 1000, and an
entity with field-level read rules doesn't support it.
Row-level security applies, so you only get the records the entity's
`rls` read rule lets your credential see. The `User` entity isn't
supported. Use [List app users](/api-reference/list-app-users) instead.
This endpoint accepts a personal API key belonging to a user with
access to the app, including a read-only key. Workspace API keys are not
accepted.
operationId: list_entities_v2_api_apps__app_id__entities__entity_name__v2_list_get
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the app that owns the entity.
title: App Id
description: ID of the app that owns the entity.
example: 6820f3a4e7b91d003c45a1f2
- name: entity_name
in: path
required: true
schema:
type: string
description: >-
Name of the entity, exactly as [List entity
schemas](/api-reference/list-entity-schemas) reports it. Don't
pass `User` here. It doesn't fail, but it reads and writes a
separate, disconnected set of records stored under that name, not
the app's real user accounts, which are managed through their own
endpoints.
title: Entity Name
description: >-
Name of the entity, exactly as [List entity
schemas](/api-reference/list-entity-schemas) reports it. Don't pass
`User` here. It doesn't fail, but it reads and writes a separate,
disconnected set of records stored under that name, not the app's
real user accounts, which are managed through their own endpoints.
example: Invoice
- name: q
in: query
required: false
description: >-
Filter as a JSON object of field names and values, for example
`{"status": "paid"}` for an exact match, or using an operator such
as `$gt` for a comparison. See [Filtering, sorting, and
paging](/developers/references/apps-api/sections/entities#filtering-sorting-and-paging)
for a full list of operators.
example: '{"status": "paid"}'
schema:
type: string
- name: limit
in: query
required: false
description: >-
Number of records on each page, from 1 to 5000, or up to 1000 with
`distinct`. Defaults to 100, and a higher value is treated as the
maximum.
example: 500
schema:
type: integer
default: 100
- name: sort
in: query
required: false
description: >-
Single field to sort by, prefixed with `-` for descending. For
example, `-created_date` returns newest first. Defaults to
`-created_date`. Sort by a field every record carries, such as
`created_date`, or by one the entity's schema declares as a string,
number, integer, or boolean.
example: '-created_date'
schema:
type: string
default: '-created_date'
- name: fields
in: query
required: false
description: >-
Comma-separated list of fields to return, which reduces the response
size on a wide entity. Reach a field inside an object with dots, as
in `customer.email`. Each record still carries its `id` whether you
ask for it or not.
example: status,amount
schema:
type: string
- name: cursor
in: query
required: false
description: >-
Pagination cursor from previous response. Leave it out for the first
page.
example: gAAAAABn7vJ...
schema:
type: string
- name: distinct
in: query
required: false
description: >-
Field whose distinct values to return instead of records, in
ascending order.
example: status
schema:
type: string
responses:
'200':
description: One page of the entity's records.
content:
application/json:
schema:
type: object
additionalProperties: true
title: EntityRecordPage
description: One page of records and the cursor for the next one.
properties:
items:
type: array
items:
anyOf:
- type: object
additionalProperties: true
description: One record in one of an app's entities.
properties:
id:
anyOf:
- type: string
- type: 'null'
description: >-
ID of the record. Pass it as `entity_id` to [Get
entity
record](/api-reference/get-entity-record),
[Update entity
record](/api-reference/update-entity-record) or
[Delete entity
record](/api-reference/delete-entity-record).
example: 6886b8d390dc7e2f4a2c91b3
title: Id
created_date:
anyOf:
- type: string
- type: 'null'
description: >-
When the record was created, as a UTC timestamp
in ISO 8601 format. A record Base44 has just
created carries a `Z` suffix, and a record read
back from storage does not.
example: '2026-06-01T09:23:41.481000'
title: Created Date
updated_date:
anyOf:
- type: string
- type: 'null'
description: >-
When the record last changed, as a UTC timestamp
in ISO 8601 format. A record Base44 has just
created carries a `Z` suffix, and a record read
back from storage does not.
example: '2026-06-04T14:07:02.115000'
title: Updated Date
created_by:
anyOf:
- type: string
- type: 'null'
description: >-
Email of the app user who created the record, or
`anonymous` when a visitor created it on an app
that needs no login. Apps that hide record
authorship leave this field out of the response.
example: jane@acme.com
title: Created By
created_by_id:
anyOf:
- type: string
- type: 'null'
description: >-
ID of the app user who created the record, or
`anonymous` when a visitor created it on an app
that needs no login.
example: 6874b0c2e1a94d0031bb77de
title: Created By Id
is_sample:
anyOf:
- type: boolean
- type: 'null'
description: >-
Whether Base44 stored the record as sample data
while the app was being built. A record you
create reports `false`.
example: false
title: Is Sample
title: EntityRecord
- type: string
- type: number
- type: boolean
description: >-
The page's records in the requested sort order, or with
`distinct` the field's values in ascending order.
example:
- id: 6886b8d390dc7e2f4a2c91b3
created_date: '2026-06-01T09:23:41.481000'
updated_date: '2026-06-04T14:07:02.115000'
created_by: jane@acme.com
created_by_id: 6874b0c2e1a94d0031bb77de
is_sample: false
amount: 4200
status: draft
customer_email: jane@acme.com
next_cursor:
anyOf:
- type: string
- type: 'null'
description: >-
Cursor for fetching the next page. The value is `null` if
there are no more pages.
example: gAAAAABn7vJ...
has_more:
type: boolean
description: Whether there are more items to fetch.
example: true
required:
- items
- next_cursor
- has_more
'400':
description: >-
The cursor is invalid, was issued to another credential, or was
issued for a different filter, sort, fields, or `distinct`. Also
returned when `skip` is set, `limit` is below 1 or not a whole
number, `q` isn't a filter Base44 can run, `sort` names more than
one field or a field it can't sort by, `distinct` names a field the
schema doesn't declare or is combined with `sort` or `fields`, or
the entity is `User`.
'401':
description: Missing or invalid credentials.
'403':
description: You don't have access to this app.
'404':
description: App not found, or the app has no entity with this name.
'422':
description: >-
A filter you passed as its own query parameter doesn't match the
type the entity's schema declares for that field.
'429':
description: >-
Rate limit exceeded. The base limit is 70 requests per minute, and
this endpoint shares it with [List entity
records](/api-reference/list-entity-records) and [Count entity
records](/api-reference/count-entity-records). A page with
`distinct` also counts against a separate limit of 15 requests per
minute. See [Rate
limits](/developers/references/apps-api/get-started/rate-limits) for
the multiplier your plan gets.
components:
securitySchemes:
PersonalAccessTokenAuth:
type: http
scheme: bearer
description: 'Personal access token, sent as `Authorization: Bearer `.'
````