> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://reference.flatfile.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://reference.flatfile.com/_mcp/server.

# Get records

GET https://api.x.flatfile.com/v1/sheets/{sheetId}/records

Returns records from a sheet in a workbook

Reference: https://reference.flatfile.com/api-reference/records/get

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `sheetId` (string, required) — ID of sheet

### Query parameters

- `versionId` (string, optional, deprecated) — Deprecated, use `commitId` instead.
- `commitId` (string, optional) — Commit ID
- `sinceVersionId` (string, optional, deprecated) — Deprecated, use `sinceCommitId` instead.
- `sinceCommitId` (string, optional) — Commit ID
- `sortField` (string, optional) — Name of field by which to sort records
- `sortDirection` (enum, optional) — Sort direction - asc (ascending) or desc (descending)
  - Allowed values: `asc`, `desc`
- `filter` (enum, optional) — Options to filter records
  - Allowed values: `valid`, `error`, `all`, `none`
- `filterField` (string, optional) — Name of field by which to filter records
- `searchValue` (string, optional) — Search for the given value, returning matching rows. For exact matches, wrap the value in double quotes ("Bob"). To search for null values, send empty double quotes ("")
- `searchField` (string, optional) — Use this to narrow the searchValue results to a specific field
- `ids` (string, optional) — The Record Ids param (ids) is a list of record ids that can be passed to several record endpoints allowing the user to identify specific records to INCLUDE in the query, or specific records to EXCLUDE, depending on whether or not filters are being applied. When passing a query param that filters the record dataset, such as 'searchValue', or a 'filter' of 'valid' | 'error' | 'all', the 'ids' param will EXCLUDE those records from the filtered results. For basic queries that do not filter the dataset, passing record ids in the 'ids' param will limit the dataset to INCLUDE just those specific records. Maximum of 100 allowed.
- `pageSize` (integer, optional) — Number of records to return in a page (default 10,000)
- `pageNumber` (integer, optional) — Based on pageSize, which page of records to return (Note - numbers start at 1)
- `includeCounts` (boolean, optional, deprecated) — **DEPRECATED** Use GET /sheets/:sheetId/counts
- `includeLength` (boolean, optional) — The length of the record result set, returned as counts.total
- `includeLinks` (boolean, optional) — If true, linked records will be included in the results. Defaults to false.
- `includeMessages` (boolean, optional) — Include error messages, defaults to false.
- `fields` (string, optional) — A list of field keys to include in the response. If not provided, all fields will be included.
- `for` (string, optional) — if "for" is provided, the query parameters will be pulled from the event payload
- `q` (string, optional) — An FFQL query used to filter the result set

## Response

### 200

- `data` (GetRecordsResponseData, required) — A list of records with optional record counts

## Errors

### 400 Bad Request Error

- `errors` (list of Error, required)

### 404 Not Found Error

- `errors` (list of Error, required)

## Types

### GetRecordsResponseData

A list of records with optional record counts

- `records` (list of RecordWithLinks, required) — List of Record objects, including links to related rows
- `success` (boolean, required)
- `commitId` (string, optional) — Commit ID
- `counts` (RecordCounts, optional)
- `versionId` (string, optional, deprecated) — Deprecated, use `commitId` instead.

### Error

- `message` (string, required)
- `key` (string, optional)

### RecordWithLinks

A single row of data in a Sheet, including links to related rows

- `id` (string, required) — Record ID
- `values` (map from string to CellValueWithLinks, required) — A single row of data in a Sheet, including links to related rows
- `valid` (boolean, optional)
- `messages` (list of ValidationMessage, optional)
- `metadata` (map from string to any, optional)
- `config` (RecordConfig, optional) — Configuration of a record or specific fields in the record

### RecordCounts

- `total` (integer, required)
- `valid` (integer, required)
- `error` (integer, required)
- `byField` (map from string to FieldRecordCounts, optional) — Counts for valid, error, and total records grouped by field key
- `errorsByField` (map from string to integer, optional, deprecated)

### CellValueWithLinks

- `layer` (string, optional)
- `links` (list of Record, optional) — List of Record objects
- `messages` (list of ValidationMessage, optional)
- `updatedAt` (datetime, optional)
- `valid` (boolean, optional)
- `value` (CellValueUnion, optional)
- `metadata` (map from string to any, optional, deprecated) — Deprecated, use record level metadata instead.

### ValidationMessage

Record data validation messages

- `field` (string, optional)
- `type` (enum, optional)
  - Allowed values: `error`, `warn`, `info`
- `source` (enum, optional)
  - Allowed values: `required-constraint`, `unique-constraint`, `custom-logic`, `unlinked`, `invalid-option`, `is-artifact`
- `message` (string, optional)
- `path` (string, optional) — This JSONPath is based on the root of mapped cell object.

### RecordConfig

Configuration of a record or specific fields in the record

- `readonly` (boolean, optional)
- `fields` (map from string to CellConfig, optional)
- `markedForDeletion` (boolean, optional)

### FieldRecordCounts

- `total` (integer, required)
- `valid` (integer, required)
- `error` (integer, required)
- `empty` (integer, required)

### Record

A single row of data in a Sheet

- `id` (string, required) — Record ID
- `values` (map from string to CellValue, required) — A single row of data in a Sheet
- `commitId` (string, optional) — Commit ID
- `config` (RecordConfig, optional) — Configuration of a record or specific fields in the record
- `metadata` (map from string to any, optional)
- `valid` (boolean, optional) — Auto-generated value based on whether the record contains a field with an error message. Cannot be set via the API.
- `messages` (list of ValidationMessage, optional, deprecated) — This record level `messages` property is deprecated and no longer stored or used. Use the `messages` property on the individual cell values instead. This property will be removed in a future release.
- `versionId` (string, optional, deprecated) — Deprecated, use `commitId` instead.

### CellValueUnion

### CellConfig

CellConfig

- `readonly` (boolean, optional)

### CellValue

- `valid` (boolean, optional)
- `messages` (list of ValidationMessage, optional)
- `value` (CellValueUnion, optional)
- `layer` (string, optional)
- `updatedAt` (datetime, optional)
- `metadata` (map from string to any, optional, deprecated) — Deprecated, use record level metadata instead.

## Examples

**Response**

```json
{
  "data": {
    "records": [
      {
        "id": "us_rc_YOUR_ID",
        "values": {
          "firstName": {
            "messages": [],
            "updatedAt": "2023-11-20T16:59:40.286Z",
            "valid": true,
            "value": "John"
          },
          "lastName": {
            "messages": [],
            "updatedAt": "2023-11-20T16:59:40.286Z",
            "valid": true,
            "value": "Smith"
          },
          "email": {
            "messages": [],
            "updatedAt": "2023-11-20T16:59:40.286Z",
            "valid": true,
            "value": "john.smith@example.com"
          }
        },
        "valid": true,
        "metadata": {},
        "config": {}
      }
    ],
    "success": true,
    "commitId": "us_vr_YOUR_ID",
    "counts": {
      "total": 1000,
      "valid": 1000,
      "error": 0
    },
    "versionId": "us_vr_YOUR_ID"
  }
}
```

**SDK Code**

```python Example0
import requests

url = "https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records"

headers = {
    "X-Disable-Hooks": "true",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```typescript Example0
import { FlatfileClient } from "@flatfile/api";

const client = new FlatfileClient({ token: "YOUR_TOKEN" });
await client.records.get("us_sh_YOUR_ID");

```

```go Example0
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Disable-Hooks", "true")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Example0
require 'uri'
require 'net/http'

url = URI("https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Disable-Hooks"] = 'true'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Example0
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records")
  .header("X-Disable-Hooks", "true")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Example0
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'X-Disable-Hooks' => 'true',
  ],
]);

echo $response->getBody();
```

```csharp Example0
using RestSharp;

var client = new RestClient("https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records");
var request = new RestRequest(Method.GET);
request.AddHeader("X-Disable-Hooks", "true");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Example0
import Foundation

let headers = [
  "X-Disable-Hooks": "true",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.x.flatfile.com/v1/sheets/us_sh_YOUR_ID/records")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```