1. API
  2. Records

Records: Get

Last updated Open markdown version

Description

A record is a piece of structured, queryable data captured from a story, the API, or the UI. See Records in the Tines docs to learn more.

Retrieve a single record.

You can find the record ID in the response from the List Records API.

For opinionated guidance on building against the Records API — schema discovery, pagination, artifacts, retries, and rate limits — see Best practices.

Request

HTTP Method: GET

Path parameter Description
record_id The ID of the record to retrieve.
Query parameter Description
record_type_id Optional The ID of the record type. When provided, the lookup is scoped to that record type — this is faster than an unscoped lookup, and returns 404 if the record ID does not belong to the given record type.
record_field_ids Optional An array of record field IDs. When provided, only the specified fields are included in the response. The id, updated_at, and case_ids fields are always returned.
resolve_artifacts Optional Boolean true or false value. When true, Artifacts (large text) fields return the full contents instead of just the artifact ID. Defaults to false.
include_children Optional Boolean true or false value. When true, child records are returned with their full field data. When false, child records are omitted from the response. By default, only child record IDs are returned. 
curl -X GET \
  https://<tenant-domain>/api/v1/records/<<record_id>> \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'

For a faster lookup, include the record type ID:

curl -X GET \
  "https://<tenant-domain>/api/v1/records/<<record_id>>?record_type_id=<<record_type_id>>" \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'

Example request with record_field_ids

To return only specific fields in the response:

curl -X GET \
  "https://<tenant-domain>/api/v1/records/<<record_id>>?record_field_ids[]=<<field_id_1>>&record_field_ids[]=<<field_id_2>>" \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'

Note: All field IDs must belong to the record's record type. A 404 error is returned if any field ID does not exist, and a 422 error is returned if any field ID belongs to a different record type.

Example request with resolve_artifacts

To return full artifact contents instead of artifact IDs:

curl -X GET \
  "https://<tenant-domain>/api/v1/records/<<record_id>>?resolve_artifacts=true" \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer <<CREDENTIAL.tines_api_key>>'

Response

A successful request will return a JSON object representing the specified record.

Artifacts (large text)

By default, Artifacts (large text) field types return a reference object containing the artifact ID and an is_artifact flag, rather than the data itself:

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

Alternatively, set resolve_artifacts=true in the request to include full artifact contents directly in the response.

Field description

Parameter Description
id The record ID.
created_at ISO 8601 timestamp representing when the record was created.
updated_at ISO 8601 timestamp representing when the record was last updated.
story The story the record was created from.
story_run_guid The story run guid the record was created from.
record_type The type of record.
records The captured data for the given instance of the record type.
record_artifacts An array of { id } objects, one per artifact attached to the record. Pass an id to the Get Artifacts API to retrieve the contents.
child_records An array of objects containing the record IDs (or full field data when include_children=true) for which this record is the parent.
child_records_truncated true when the child records list was capped. Only present when truncation occurred; otherwise absent from the response.
parent_record The ID of this record's parent record.
case_ids An array of case IDs linked to this record.
result The captured data in key-value format.

Sample response

{
  "id": 59,
  "created_at": "2023-06-14T15:09:02Z",
  "updated_at": "2023-06-14T15:09:02Z",
  "story": {
    "id": 8,
    "name": "Create new IOC"
  },
  "story_run_guid": "82c8e2c8-ab56-49c9-bdb9-1ea5b7fd5b2e",
  "record_type": {
    "id": 1,
    "name": "Alert"
  },
  "records": [
    {
      "name": "Story name",
      "value": "Create new IOC"
    },
    {
      "name": "Timestamp",
      "value": "2023-06-14 16:09:02"
    },
    {
      "name": "Name",
      "value": "Example"
    },
    {
      "name": "Description",
      "value": {
        "id": 674623,
        "is_artifact": true
      }
    }
  ],
  "record_artifacts": [{ "id": 674623 }],
  "child_records": [
    {
      "id": 9
    }
  ],
  "parent_record": {
    "id": 66
  },
  "case_ids": [4, 2],
  "result": {
    "id": 59,
    "updated_at": "2023-06-14T15:09:02Z",
    "case_ids": [4, 2],
    "Story name": "Create new IOC",
    "Record ID": 59,
    "Timestamp": "2023-06-14 16:09:02",
    "Name": "Example",
    "Description": {
      "id": 674623,
      "is_artifact": true
    }
  }
}
Was this helpful?