ListRetrohunts parity mapping

Supported in:

This guide details the request and response mapping specifications and property parity analysis for migrating from the legacy Backstory Rules Engine API (ListRetrohunts) to the modern Chronicle API (ListRetrohunts).

Protocol and mapping overview

Feature Legacy API (ListRetrohunts) Modern Chronicle API (ListRetrohunts)
HTTP Method GET GET
Permissions Partner token or legacy API keys chronicle.googleapis.com/retrohunts.list

Request payload field-by-field parity

The modern Chronicle API ListRetrohuntsRequest scopes queries under target parent rule revisions and replaces standalone state fields with AIP-160 filters.

Legacy Field (ListRetrohuntsRequest) Modern Field (ListRetrohuntsRequest) Field type Parity & Migration Notes
version_id parent (in HTTP path) string Google Cloud Scoping / Architectural Shift: Legacy passed {rule_id} or {rule_id}@{version_ts} in the URL path parameter version_id. The modern API routes this using canonical Google Cloud parent resource paths: projects/{project}/locations/{location}/instances/{instance}/rules/{rule_id@revision_id}.
state filter enum $\rightarrow$ string Syntax Shift: Legacy accepted an explicit enum field (Retrohunt.State state). The modern API replaces this with standard AIP-160 filter expression strings targeting the state field (for example, state = "DONE" or state = "RUNNING").
page_size page_size int32 Parity Mapped: Pagination page size limit. Rename to pageSize in JSON.
page_token page_token string Parity Mapped: Paging resumption token. Rename to pageToken in JSON.

Response payload field-by-field parity

Both APIs return pagination lists of retrohunt execution resources and continuation tokens.

Legacy Field (ListRetrohuntsResponse) Modern Field (ListRetrohuntsResponse message) Field type Parity & Migration Notes
retrohunts retrohunts repeated Retrohunt Parity Mapped: Array list of retrohunt execution records. Rename to retrohunts in JSON.
next_page_token next_page_token string Parity Mapped: Token to retrieve subsequent pages of retrohunts. Rename to nextPageToken in JSON.

Nested Retrohunt property mappings

The fields mapping inside individual Retrohunt items is as follows:

Legacy Field (Retrohunt message) Modern Field (Retrohunt message) Field type Parity & Migration Notes
retrohunt_id / rule_id / version_id name string Consolidated: Legacy separate identifier strings are unified into the canonical Google Cloud resource path under name: projects/{project}/locations/{location}/instances/{instance}/rules/{rule_id@revision_id}/retrohunts/{retrohunt_id}.
event_start_time process_interval.start_time Timestamp Mapped inside the process_interval object (Interval.start_time).
event_end_time process_interval.end_time Timestamp Mapped inside the process_interval object (Interval.end_time).
retrohunt_start_time execution_interval.start_time Timestamp Mapped inside the execution_interval object (Interval.start_time).
retrohunt_end_time execution_interval.end_time Timestamp Mapped inside the execution_interval object (Interval.end_time).
state state enum Parity Mapped / Value Enrichment: Maps directly to State enum (RUNNING, DONE, CANCELLED). The modern API adds support for FAILED (value 4) when execution fails.
progress_percentage progress_percentage float Parity Mapped: Percent progress towards completion (0.00 to 100.00). Rename to progressPercentage in JSON.

Key differences

  • Service Consolidation and Renaming:
    • Legacy retrohunt listing was housed under RulesEngineService with URL pattern /v2/detect/rules/{version_id}/retrohunts.
    • Modern Chronicle API consolidates this under RuleService (ListRetrohunts), using standard Google Cloud parent paths (projects/.../rules/{rule}/retrohunts).
  • Google Cloud Project Scoping and Canonical Names:
    • Scoped natively under parent project instance rule bindings. Separate rule, version, and retrohunt IDs are consolidated into standard Google Cloud canonical resource names.
  • Filter-Based State Queries:
    • The standalone state enum query parameter is replaced by flexible AIP-160 string filter expressions (filter = "state = 'DONE'").
  • Time Window Consolidation (Interval):
    • Standalone timestamp pairs for event ranges and execution durations on returned objects are structured into standard google.type.Interval objects (process_interval and execution_interval).
  • IAM Permissions:
    • Request validation maps to standard Cloud IAM permission check (chronicle.googleapis.com/retrohunts.list).