> ## Documentation Index
> Fetch the complete documentation index at: https://nango.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Get records
> Returns data synced with Nango Sync
Requires an API key with the `environment:records:read` scope. [Learn more about API key scopes](/reference/backend/http-api/api-keys#scopes).
## Receive webhooks on data updates
Receive webhooks from Nango when new records are available. Follow the [sync functions section](/guides/functions/syncs/sync-functions).
**Data availability**: Records are subject to Nango's [data retention policies](/guides/platform/security#synced-records-retention). Records not updated for 30 days will have their payload pruned (only metadata remains). Records from syncs not executed for 60 days are permanently deleted. Fetch and store records promptly in your own system.
## Response
This endpoint returns a list of records, ordered by modification date ascending. If some records are updated while you paginate through this endpoint, you might see these records multiple times.
A response may contain fewer records than `limit` when records have a large size. Always check `next_cursor` and continue paginating until it is `null`.
### Default behavior
By default this returns an array of objects in the data model that you queried with some metadata about each record.
```json theme={null}
{
records:
[
{
id: 123,
..., // Fields as specified in the model you queried
_nango_metadata: {
deleted_at: null,
last_action: 'ADDED',
first_seen_at: '2023-09-18T15:20:35.941305+00:00',
last_modified_at: '2023-09-18T15:20:35.941305+00:00',
cursor: 'MjAyNC0wMy0wNFQwNjo1OTo1MS40NzE0NDEtMDU6MDB8fDE1Y2NjODA1LTY0ZDUtNDk0MC1hN2UwLTQ1ZmM3MDQ5OTdhMQ=='
}
},
...
],
next_cursor: "MjAyMy0xMS0xN1QxMTo0NzoxNC40NDcrMDI6MDB8fDAzZTA1NzIxLWNiZmQtNGYxNS1iYTNhLWFlNjM2Y2MwNmEw=="
}
```
## OpenAPI
````yaml GET /records
openapi: 3.1.0
info:
title: Nango API
description: Nango API specs used to authorize & sync data with external APIs.
version: 1.0.0
servers:
- url: https://api.nango.dev
description: Production server
- url: http://localhost:3003
description: Local server
security:
- bearerAuth: []
externalDocs:
url: https://nango.dev/docs/reference/backend/http-api/authentication
paths:
/records:
get:
summary: Get synced records
description: Returns data synced with Nango Sync
parameters:
- name: model
in: query
required: true
schema:
type: string
description: The data model to fetch
- name: cursor
in: query
required: false
schema:
type: string
description: >
A marker used to fetch records modified after a specific point in
time. If not provided, all records are returned. Each record
includes a cursor value found in _nango_metadata.cursor. Save the
cursor from the last record retrieved to track your sync progress.
Use the cursor parameter together with the limit parameter to
paginate through records. The cursor is more precise than
modified_after, as it can differentiate between records with the
same modification timestamp.
- name: limit
in: query
required: false
schema:
type: integer
description: >
The maximum number of records to return. Defaults to 100. A response
may contain fewer records than `limit` when records have a large
size. Always check `next_cursor` and continue paginating until it is
`null`.
- name: filter
in: query
required: false
schema:
type: string
enum:
- added
- updated
- deleted
description: >-
Filter to only show results that have been added or updated or
deleted.
- name: modified_after
in: query
required: false
schema:
type: string
format: date-time
description: >-
A timestamp (e.g., 2023-05-31T11:46:13.390Z) used to fetch records
modified after this date and time. If not provided, all records are
returned. The modified_after parameter is less precise than cursor,
as multiple records may share the same modification timestamp.
- name: delta
in: query
required: false
deprecated: true
schema:
type: string
description: >-
DEPRECATED (use modified_after) Timestamp, e.g.
2023-05-31T11:46:13.390Z. If passed, only records modified after
this timestamp are returned, otherwise all records are returned.
- name: ids
in: query
required: false
description: >-
An array of string containing a list of your records IDs. The list
will be filtered to include only the records with a matching ID.
schema:
type: array
items:
type: string
maxItems: 100
- name: variant
in: query
required: false
schema:
type: string
description: The variant of the model to fetch
- name: Connection-Id
in: header
required: true
description: The connection ID used to create the connection.
schema:
type: string
- name: Provider-Config-Key
in: header
required: true
description: The integration ID used to create the connection (aka Unique Key).
schema:
type: string
responses:
'200':
description: Successfully returned records
content:
application/json:
schema:
type: object
properties:
records:
type: array
items:
type: object
properties:
your-properties:
type: string
description: The data Nango synced in for you
example: >-
Your synced data, in the schema you (or Nango)
defined in script
_nango_metadata:
type: object
properties:
deleted_at:
anyOf:
- type: string
format: date-time
- type: 'null'
description: >-
The timestamp at which Nango detected the record
as deleted
last_action:
type: string
description: The last action seen on this record
enum:
- ADDED
- UPDATED
- DELETED
first_seen_at:
type: string
description: >-
The timestamp at which Nango first saw this
record
example: '2023-09-18T15:20:35.941305+00:00'
format: date-time
last_modified_at:
type: string
description: >-
The timestamp at which Nango last detected a
change to this record
example: '2023-09-18T15:20:35.941305+00:00'
format: date-time
cursor:
type: string
description: >-
The current cursor of the record. Use this to
fetch records updated after this record
example: >-
MjAyNC0wMy0wNFQwNjo1OTo1MS40NzE0NDEtMDU6MDB8fDE1Y2NjODA1LTY0ZDUtNDk0MC1hN2UwLTQ1ZmM3MDQ5OTdhMQ==
pruned_at:
anyOf:
- type: string
format: date-time
- type: 'null'
description: >-
The timestamp at which the record payload was
pruned (emptied)
next_cursor:
type: string
description: The base64-encoded cursor for pagination
example: >-
MjAyMy0xMS0xN1QxMTo0NzoxNC40NDcrMDI6MDB8fDAzZTA1NzIxLWNiZmQtNGYxNS1iYTNhLWFlNjM2Y2MwNmEw==
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
components:
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/StdError'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/StdError'
schemas:
StdError:
type: object
additionalProperties: false
properties:
error:
type: object
additionalProperties: false
required:
- code
properties:
code:
type: string
message:
type: string
errors:
type: array
items:
type: object
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: The secret key from your Nango environment.
````