--- title: List url: https://www.tines.com/stories/docs/api/records/list/ updated: 2026-07-15T13:53:43+00:00 description: Retrieve a list of records. --- *[tines.com](https://www.tines.com/llms.txt) › [Docs](https://www.tines.com/stories/docs/llms.txt) › [Tines API](https://www.tines.com/stories/docs/api/llms.txt) › [Records](https://www.tines.com/llm/stories/docs/api/records.md)* # List *[View on tines.com](https://www.tines.com/stories/docs/api/records/list/)* ## Description Retrieve a list of records. If you need aggregates — counts, sums, averages, grouped breakdowns — reach for the [Query records API](/api/records/query) instead of paging through this endpoint and aggregating client-side. See [Best practices](/api/records/best-practices) for pagination, filter operator, and artifact-handling guidance. 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) See the [Get Records API](/api/records/get) to learn more about records. ## 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** Set to the string `"true"` to filter by records created in test stories. Defaults to `false`. | | parent_ids | **Optional** An array of parent record IDs (max 100). 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`, `IS_NONE_OF`, `CONTAINS`, `STARTS_WITH`, or `ENDS_WITH`. Note: `EQUAL`, `NOT_EQUAL`, `IS_ANY_OF`, `IS_NONE_OF`, `CONTAINS`, `STARTS_WITH`, and `ENDS_WITH` are case insensitive. A request can include at most one of the pattern filters (`CONTAINS`, `STARTS_WITH`, or `ENDS_WITH`). | | value | Depending on the operator, a string, number, or omitted. For `IS_ANY_OF` and `IS_NONE_OF` operators, provide an array of values (max 10 entries) instead of a single value. For `CONTAINS`, `STARTS_WITH`, and `ENDS_WITH` operators, provide a string value of at least three characters. Values are compared as strings and case-insensitively — a JSON boolean `true` stored in a record field matches the filter value `"true"` or `"TRUE"`. Store fields as strings if you plan to filter on them. Note: `IS_ANY_OF` and `IS_NONE_OF` are only available for text, text fixed enums, and number fields. `CONTAINS`, `STARTS_WITH`, and `ENDS_WITH` are only available for text and text fixed enum fields. | ### Example request with search filters Because this is a `GET` request, `filters` must be supplied as a single JSON array string in the query string (URL-encode it if your HTTP client doesn't handle that automatically). It is not a repeated or plain query parameter. A value that isn't valid JSON returns a `400` response with the body `["Invalid filters: not JSON parsable"]`. 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=[{\"field_id\":\"5\",\"operator\":\"EQUAL\",\"value\":\"ALERT\"}]" \ -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 <>' ``` ## 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](/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 | Default field on every record type: the name of the story that created this record. | | Timestamp | Default field on every record type: the date and time the record was created. | | Record ID | Default field on every record type: the unique ID of the record. Can be used to filter records. | | Updated at | Default field on every record type: the date and time the record was last updated. | | _(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": [ { "id": 1, "updated_at": "2023-06-06T16:18:34Z", "case_ids": [1, 2], "parent_record": null, "Story name": "Create new issue", "Timestamp": "2023-06-06 16:18:34", "Record ID": 1, "Updated at": "2023-06-06 16:18:34", "Alert": "High" }, { "id": 2, "updated_at": "2023-06-13T18:13:15Z", "case_ids": [1], "parent_record": null, "Story name": "Create new issue", "Timestamp": "2023-06-13 18:13:15", "Record ID": 2, "Updated at": "2023-06-13 18:13:15", "Alert": "Medium" } ], "meta": { "current_page": "https:///api/v1/records?record_type_id=1&per_page=20&page=1", "previous_page": null, "next_page": null, "next_page_number": null, "per_page": 20, "pages": 1, "count": 2 } } ```