List

Description

Retrieve a list of records.

The record type ID appears in the URL when viewing records: https://<<META.tenant.domain>>/records/types/{record_type_id}. Field IDs are visible when editing a record type (Actions → Edit), or can be retrieved from the List Record Types API.

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 to filter the results (optional if record_type_id is present).
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 Optional An array of story IDs to filter the results.
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.
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.

Supported parameters in filters

Parameters Description
field_id The record field (i.e. record column) id.
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, or IS_FALSE.
value Depending on the operator, a string, number, or omitted.

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.

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 the Artifacts (large text) field types return only the ID of the Artifacts, not the Artifacts data itself. 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

Parameter Description
record_results Array of objects each representing a record.
id Integer ID of the record.
Story name The name of the story this record was created in.
Timestamp The timestamp representing the date and time the record was created.

Sample response

{
  "record_results": [
    {
      "Story name": "Create new issue",
      "Timestamp": "2023-06-06 16:18:34",
      "Alert": "High",
      "case_ids": [1, 2],
      "id": 1
    },
    {
      "Story name": "Create new issue",
      "Timestamp": "2023-06-13 18:13:15",
      "Alert": "Medium",
      "case_ids": [1],
      "id": 2
    },
    {
      "Story name": "Create new issue",
      "Timestamp": "2023-06-13 18:13:16",
      "Alert": "Low",
      "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?