Get a range of records

To get a range of records, use an HTTP GET method with the records API endpoint specifying the database name, the layout, and additional information to specify a starting record and the number of records. Optionally, you can specify the sort order of the records. You can also specify portal information to limit the number of related records that are returned.

HTTP method

GET

URL

Format 1 (returns up to the first 100 records):
/fmi/data/version/databases/database-name/layouts/layout-name/records

Format 2 (returns a range of records):
/fmi/data/version/databases/database-name/layouts/layout-name/records?_offset=starting-record&_limit=number-of-records

Format 3 (returns a sorted range of records):
/fmi/data/version/databases/database-name/layouts/layout-name/records?_offset=starting-record&_limit=number-of-records&_sort=[{ "fieldName": "field-name", "sortOrder": "sort-order" }, { ... }]

Format 4 (includes a range of records with a limited range of related records):
/fmi/data/version/databases/database-name/layouts/layout-name/records?_offset=starting-record&_limit=number-of-records&portal=["portal-name1", "portal-name2", ...]&_offset.portal-name1=starting-record&_limit.portal-name1=number-of-records

version – the FileMaker Data API version requested can use v1, v2, or vLatest

  • version 1 (v1) - the structure for returned portal data is based on the view setting (Form View or Table View) of the specified layout.

    • Form View - returns all related records

    • Table View - returns the first related record

      Note  Changing the view setting alters the portal data structure for the returned value.

  • version 2 (v2) - the structure for returned portal data is based on Form View.

  • latest version (vLatest) - the behavior is based on the last version of the API.

database-name – the name of the hosted database

layout-name – the name of the layout to use as the context for getting the record

For _offset, starting-record is the record number of the first record in the range of records.

For _limit, number-of-record specifies the maximum number of records that should be returned.

For the _sort specification, the information must be specified in JSON format. field-name is the name of a field to use as the basis for sorting the records. You can specify multiple field names. For sort-order, specify the ascend or descend keyword, or specify a value list name.

For portals:

  • The portal portion of the URL is optional. If portal is omitted and the layout includes portals, the call will return related records from all of the portals on the layout. So, for better performance on layouts with portals, use portal to specify only the portals you need to get related records from.

  • Only the related records that are possible to view in a portal are returned. In the Portal Setup dialog in FileMaker Pro, these options can affect which records can be returned:

    • Allow vertical scrolling - If selected, all records that can be scrolled into view are returned. If deselected, only the number of records between Initial row and Number of rows (those that are visible without scrolling) are returned.

    • Filter portal records - If selected, only the filtered records are returned.

  • portal-name-n is a portal containing the related records. A portal name can be either the object name shown in the Inspector in FileMaker Pro or the related table name. You can specify multiple portal names.

  • For _offset.portal-name-n, starting-record is the record number of the first portal record in the range of related records. If not specified, the default value is 1.

  • For _limit.portal-name-n, number-of-record specifies the maximum number of related records that should be returned. If not specified, the default value is 50.

Other optional URL parameters:

  • layout.response - Returns the response data in the context of a different layout. The specified layout should be for the same base table as the current layout. Specifying a layout for a different base table can produce unexpected results.

  • dateformats - Specifies the format of date and timestamp fields. The value is 0 for US formats, 1 for the file locale's formats, or 2 for ISO 8601 formats. If not specified, the default value is 0.

  • script.prerequest, script.presort, script - Runs FileMaker scripts as part of the request. See Run a script with another request.

HTTP header

Authorization: Bearer session-token, where session-token is the unique X-FM-Data-Access-Token value for the database session
Parameters None
Response

The record data in JSON format and a messages array showing an error code of 0.

Copy 
{
  "response": {
    "data": [
      ... 
    ]
  },
  "messages": [
    {
      "code": "0",
      "message": "OK"
    }
  ]
}

See Error responses.

Notes 

  • You can use optional parameters to specify omit requests, the sort order (_sort), starting record (_offset), number of records (_limit), and portals for limiting the number of related records that are returned. The _offset, _limit, and _sort parameters work on records found in the layout's table and not related portal records. To restrict the number of records and rows to display in a related set, specify the _offset.portal-name-n and _limit.portal-name-n parameters.

  • If you omit the _offset and _limit values, the default offset is 1 and the default limit for records is 100: _offset=1&_limit=100

  • If you omit the sortOrder keyword, the default is ascend. For example, &_sort=[{ "fieldName": "recordId" }] is treated as: &_sort=[{ "fieldName": "recordId", "sortOrder": "ascend" }]