--- title: List url: https://www.tines.com/docs/api/records/list/ updated: 2026-05-06T18:20:13+00:00 description: Retrieve a list of records. --- *[tines.com](https://www.tines.com/llms.txt) › [Docs](https://www.tines.com/llms.txt) › [Tines API](https://www.tines.com/llms.txt) › [Records](https://www.tines.com/llm/docs/api/records.md)* # List *[View on tines.com](https://www.tines.com/docs/api/records/list/)* ## Description Retrieve a list of records. To find the record type ID to filter against, navigate to any record page at `https:///records`. Then, click the dropdown menu at the top right and select `Copy record type ID`. Alternatively, you may find the record type ID (and field IDs) in that same menu under `Manage record type`. This information may also be retrieved from the [List Record Types API](/api/records/record_types/list). ![Copy record type ID](https://www.datocms-assets.com/55802/1764706143-copy-record-id-edited.png) ## Request HTTP Method: **GET** | Query Parameter | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | record_type_id | The ID of the record type (optional if `record_field_ids` are present). | | record_field_ids | An array of record field IDs that determines which fields (columns) are included in each record result (optional if `record_type_id` is present). When omitted and `record_type_id` is provided, all fields of the record type are returned. | | range_start | **Optional** The start time for the time range of records (ISO 8601 timestamp). | | range_end | **Optional** The end time for the time range of records (ISO 8601 timestamp). | | story_ids | **Deprecated** **Optional** An array of _internal_ story IDs to filter the results. Cannot be used with `story_container_ids`. In test mode, it translates to test story IDs. Note: this is a legacy field and does not match the IDs in the URL of a story. It matches the IDs used in the Records view. Please use `story_container_ids` to match the behavior of other endpoints that reference Story ID. | | story_container_ids | **Optional** An array of story IDs to filter the results. Cannot be used with `story_ids`. | | order_direction | **Optional** The direction to order records: `ASC` or `DESC`. Defaults to `DESC`. | | order_field_id | **Optional** The ID of the field used to order records. Supports custom fields as well as default fields such as Timestamp and Updated at. When omitted, records are ordered by creation date. | | per_page | **Optional** Set the number of records returned per page. Defaults to 20, maximum is 500. | | page | **Optional** The page number of results to fetch. | | filters | **Optional** An array of objects each specifying a record filter (see the table below). | | test_mode | **Optional** Boolean `true` or `false` value. Specify whether to filter by records created in test stories. | | parent_ids | **Optional** An array of parent record IDs. Returns only first-degree child records of the specified parent records. Use this to efficiently retrieve all children of one or more parent records. | **Important:** The `record_field_ids` parameter is different from the `field_id` used inside `filters`. The `record_field_ids` parameter controls which fields (columns) appear in each record result in the response, while `field_id` in `filters` specifies which fields to apply filter conditions to when selecting which records to return. Supported parameters in `filters` | Parameters | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | field_id | The record field (i.e. record column) id to apply the filter condition to. | | operator | `EQUAL`, `NOT_EQUAL`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`, `IS_EMPTY`, `IS_NOT_EMPTY`, `IS_TRUE`, `IS_FALSE`, `IS_ANY_OF`, or `IS_NONE_OF`. Note: `EQUAL`, `NOT_EQUAL`, `IS_ANY_OF`, and `IS_NONE_OF` are case insensitive. | | value | Depending on the operator, a string, number, or omitted. For `IS_ANY_OF` and `IS_NONE_OF` operators, provide an array of values instead of a single value. Note: `IS_ANY_OF` and `IS_NONE_OF` are only available for text, text fixed enums, and number fields. | ### Example request with search filters Sample request params: ```json { "filters": [ { "field_id": "5", "operator": "EQUAL", "value": "ALERT" } ], "record_type_id": "1", "range_end": "2023-07-03T00:00:00Z", "range_start": "2022-07-03T23:59:59Z" } ``` Example request: ```bash curl -v \ -X GET \ --location \ "https:///api/v1/records?range_end=2023-07-03T00:00:00Z&range_start=2022-07-03T23:59:59Z&record_type_id=1&filters==[{"value":"ALERT","operator":"EQUAL","field_id":"5"}]" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` Tip: You can copy the cURL command of the record table and its filters you're viewing in the Tines app. ### Example request with IS_ANY_OF operator Sample request params using `IS_ANY_OF` with an array of values: ```json { "filters": [ { "field_id": "5", "operator": "IS_ANY_OF", "value": ["ALERT", "WARNING", "CRITICAL"] } ], "record_type_id": "1" } ``` Example request: ```bash curl -v \ -X GET \ --location \ "https:///api/v1/records?record_type_id=1&filters=[{\"field_id\":\"5\",\"operator\":\"IS_ANY_OF\",\"value\":[\"ALERT\",\"WARNING\",\"CRITICAL\"]}]" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ### Example request with story_container_ids To retrieve records from specific story containers (workflows): ```bash curl -v \ -X GET \ --location \ "https:///api/v1/records?record_type_id=1&story_container_ids[]=123&story_container_ids[]=456" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` To retrieve records from test stories within story containers: ```bash curl -v \ -X GET \ --location \ "https:///api/v1/records?record_type_id=1&story_container_ids[]=123&test_mode=true" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` **Note:** You cannot specify both `story_ids` and `story_container_ids` in the same request. ### Example request with parent_ids To retrieve all first-degree child records of specific parent records: ```bash curl -v \ -X GET \ --location \ "https:///api/v1/records?record_type_id=1&parent_ids[]=123&parent_ids[]=456" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` To retrieve child records of a single parent: ```bash curl -v \ -X GET \ --location \ "https:///api/v1/records?record_type_id=1&parent_ids[]=123" \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <>' ``` ### Rate limit Please be aware that usage of this endpoint is subject to a rate limit of 400 requests per minute. ## Response A successful request will return a JSON object containing the records the requesting token has access to. ### Artifacts (large text field) Please note that Artifacts (large text) field types do not return the Artifacts data itself, but instead return a reference object containing the artifact ID and an `is_artifact` flag: ```json { "id": 674623, "is_artifact": true } ``` This `id` is the `artifact_id` you need to pass to the [GET Artifacts (large text) API](https://www.tines.com/api/records/artifacts/get) endpoint to retrieve the actual contents. ### Field description The response contains these top-level fields: | Field | Description | | -------------- | -------------------------------------------------------------------------------------- | | record_type | Object containing the record type information with `id` (integer) and `name` (string). | | record_results | Array of objects, each representing a record (see below). | | meta | Object containing pagination information. | Each object in the `record_results` array contains the following fields: | Field | Description | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | Integer ID of the record. | | updated_at | ISO 8601 timestamp representing when the record was last updated. | | case_ids | Array of integer case IDs that this record is associated with. | | parent_record | Object with `id` (integer) for this record's parent, or `null` if this record has no parent. Same shape as [Get record](/api/records/get). | | Story name | The name of the story this record was created in. This is a default field present on every record type. | | Timestamp | The date and time the record was created. This is a default field present on every record type. | | _(other fields)_ | Each remaining key-value pair corresponds to a record field. The keys are the field names and the values are the field contents. Which fields appear depends on the `record_field_ids` parameter (or all fields if only `record_type_id` is provided). | ### Sample response ```json { "record_type": { "id": 1, "name": "Alerts" }, "record_results": [ { "Story name": "Create new issue", "Timestamp": "2023-06-06 16:18:34", "Alert": "High", "updated_at": "2023-06-06T16:18:34Z", "case_ids": [1, 2], "parent_record": null, "id": 1 }, { "Story name": "Create new issue", "Timestamp": "2023-06-13 18:13:15", "Alert": "Medium", "updated_at": "2023-06-13T18:13:15Z", "case_ids": [1], "parent_record": null, "id": 2 }, { "Story name": "Create new issue", "Timestamp": "2023-06-13 18:13:16", "Alert": "Low", "updated_at": "2023-06-13T18:13:16Z", "case_ids": [], "parent_record": null, "id": 3 } ], "meta": { "current_page": "https:///api/v1/records?per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, // Max: 500 "pages": 1, "count": 3 } } ```