List

Description

Retrieve a list of records.

To find the record type ID to filter against, navigate to any record page at https://<<META.tenant.domain>>/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.

Copy record type ID

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:

{
  "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:

curl -v \
-X GET \
--location \
  "https://<<META.tenant.domain>>/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 <<CREDENTIAL.tines_api_key>>'

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:

{
  "filters": [
    {
      "field_id": "5",
      "operator": "IS_ANY_OF",
      "value": ["ALERT", "WARNING", "CRITICAL"]
    }
  ],
  "record_type_id": "1"
}

Example request:

curl -v \
-X GET \
--location \
  "https://<<META.tenant.domain>>/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 <<CREDENTIAL.tines_api_key>>'

Example request with story_container_ids

To retrieve records from specific story containers (workflows):

curl -v \
-X GET \
--location \
  "https://<<META.tenant.domain>>/api/v1/records?record_type_id=1&story_container_ids[]=123&story_container_ids[]=456" \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'

To retrieve records from test stories within story containers:

curl -v \
-X GET \
--location \
  "https://<<META.tenant.domain>>/api/v1/records?record_type_id=1&story_container_ids[]=123&test_mode=true" \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'

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:

curl -v \
-X GET \
--location \
  "https://<<META.tenant.domain>>/api/v1/records?record_type_id=1&parent_ids[]=123&parent_ids[]=456" \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'

To retrieve child records of a single parent:

curl -v \
-X GET \
--location \
  "https://<<META.tenant.domain>>/api/v1/records?record_type_id=1&parent_ids[]=123" \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'

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:

{ "id": 674623, "is_artifact": true }

This id is the artifact_id you need to pass to the GET Artifacts (large text) API 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.
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

{
  "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],
      "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],
      "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": [],
      "id": 3
    }
  ],
  "meta": {
    "current_page": "https://<<META.tenant.domain>>/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
  }
}
Was this helpful?