View history (technical preview)

Use the history_records resource to view change history for entities.

Overview

A history record is created when an item is created or when changes are saved to an existing item.

The history_records resource provides parsed, field-level history details that are broader than the user interface history view.

Because this is a technical preview resource, include the ALM-OCTANE-TECH-PREVIEW request header with the value true in all history_records API requests.

Note: As a technical preview, this resource is subject to change.

Results are capped at 10,000 records by default. The MAX_LIMIT_ELASTIC configuration parameter can lower this cap, but cannot raise it.

URIs by context

Context URI
Workspace

.../api/shared_spaces/<space_id>/workspaces/<workspace_id>/history_records

Build history queries

Use the query clause to filter results. Separate query conditions with semicolons (;), which act as logical AND.

Supported query items

Query item Purpose
entity_type Filter by entity type, such as story, defect, or pipeline.
entity_id Filter by a specific entity ID.
history_log_id Filter by a specific history log ID.
action Filter by operation type: create, update, or delete.
user_id Filter by the user who made the change.
timestamp Filter by time range, for example with GE and LE operators.

Notes:

  • If you omit query, the API can return large cross-entity history sets. Always filter for performance and relevance.

  • You can combine standard collection clauses, such as limit, offset, and fields, with query.

  • When you use entity_id, also specify entity_type to avoid matching multiple entity types that share the same ID.

  • Users with data visibility restrictions must include both entity_type and entity_id in the query.

  • When filtering by user_id, use the site user ID for site-level requests and the space user ID for workspace-level requests.

  • To see which entities support history, check the history feature in Entity metadata reference.

Request examples

The following examples show common history request patterns with explicit fields and query clauses.

View the history of one defect 

GET .../history_records?fields=entity_type,entity_id,field_name,action,user_id,user_name,timestamp,history_log_id,old_value,value&query="entity_type EQ ^defect^;entity_id EQ 2002"

View history of defects modified by one user 

GET .../history_records?fields=entity_type,entity_id,field_name,action,user_id,timestamp,history_log_id&query="entity_type EQ ^defect^;user_id EQ 2002"

View entities deleted by one user in a time range 

GET .../history_records?fields=entity_type,entity_id,action,user_id,timestamp,history_log_id&query="user_id EQ 2002;action EQ ^delete^;timestamp GE ^2019-01-01T20:59:59Z^"

Offset for history records

The history_records resource is parsed from history_log. One history log can contain multiple history records.

When using offset with history_records, include originalSkip and innerOffset to identify the exact position within the parsed results.

  • originalSkip: How many history logs to skip.

  • innerOffset: How many records to skip within the selected history log.

The server adds originalSkip and innerOffset to the next-page link when another page is available. Do not change these values manually, because doing so can produce inconsistent results.

The total_count value for history_records is -1.

GET .../history_records?offset=1000&originalSkip=98&innerOffset=16

Response field highlights

Each result is a history_record event.

Common fields returned in history records: type, entity_type, entity_id, entity_physical_id, field_name, action, user_id, user_name, timestamp, history_log_id, old_value, value, mode, originated_by, session_id, request_id, workspace_id.

Common history record schema

{
  "type": "history_record",
  "timestamp": "2018-12-16T12:49:47Z",
  "session_id": "93d57993-2560-423b-bfd8-7f8eb0ca4277",
  "entity_physical_id": 1005,
  "entity_id": "1005",
  "workspace_id": 1002,
  "entity_type": "defect",
  "user_id": 2002,
  "user_name": "Marta Santora",
  "action": "create",
  "field_name": "release",
  "history_log_id": "5923",
    "mode": null,
    "originated_by": null,
  "old_value": null,
  "value": "2002",
  "request_id": "835y6j2d30lm7iyvlo8nxpk2d"
}

See also