ListArtifactAssets parity mapping

Supported in:

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

Protocol and mapping overview

Feature Legacy API (ListArtifactAssets) Modern Chronicle API (FindRelatedEntities)
HTTP method GET GET
Permissions Partner token or legacy API keys chronicle.googleapis.com/entities.findRelatedEntities

Request payload field-by-field parity

The modern Chronicle API FindRelatedEntitiesRequest generalizes graph traversal beyond assets and replaces standalone timestamp pairs with structured intervals.

Legacy field (ListArtifactAssetsRequest) Modern field (FindRelatedEntitiesRequest) Field type Parity and migration notes
— instance (in HTTP path) string Google Cloud scoping context / new field: Scopes entity graph traversal under target instance environments: projects/{project}/locations/{location}/instances/{instance}.
artifact entity_id / field_and_value oneof id (string / FieldAndValue) Architectural shift: Legacy accepted an ArtifactIndicator struct. The modern API generalizes graph traversal by taking either an exact entity_id string or a structured field_and_value locator (for example, matching a domain name or IP field). Rename to entityId or fieldAndValue in JSON.
start_time / end_time time_range Interval Consolidated: Legacy distinct start and end timestamps are mapped into a single required google.type.Interval object (time_range.start_time and time_range.end_time). Rename to timeRange in JSON.
page_size limit int32 Parity mapped and parameter renaming: Sets the maximum number of entities returned (max 100). In Chronicle API, the page_size field is deprecated and replaced by limit.
page_token — (deprecated) string Retired: Pagination is unsupported for FindRelatedEntities; legacy page_token is deprecated and ignored.
— entity_types / domain_type repeated enum / enum New parameters: Allows filtering returned graph relationships by target entity_types (for example, ASSET, USER) or specifying DNS relationship hierarchy (domain_type: DOMAIN_TYPE_SIBLING, DOMAIN_TYPE_SUBDOMAIN).
— exclude_first_last_seen / include_all_udm_event_types_for_first_last_seen bool / bool New parameters: Latency optimization toggles controlling whether to compute first/last seen observation metrics across UDM event stores.

Response payload field-by-field parity

While legacy backstory returned asset-specific info structures, the modern API returns generalized Entity messages and truncation indicators.

Legacy field (ListArtifactAssetsResponse) Modern field (FindRelatedEntitiesResponse) Field type Parity and migration notes
assets related_entities repeated Entity Parity mapped and generalized: Legacy returned AssetFirstLastSeenInfo structures limited strictly to asset indicators. The modern API returns a repeated list of generalized Entity messages (related_entities) representing any linked entity graph node (assets, users, domains). Rename to relatedEntities in JSON.
next_page_token — (deprecated) string Retired: Since pagination is disabled for related entity queries, next_page_token is deprecated.
uri — repeated string Retired: Backstory UI deep link URL arrays are removed from the API response payload.
— has_more_entities bool New field: Boolean indicator returning true if additional related entities exist in the graph but were truncated due to the limit threshold. Rename to hasMoreEntities in JSON.
— result_time_range Interval New field: Time window bounding the returned entity relationships. Rename to resultTimeRange in JSON.

Nested entity and asset info property mappings

The fields mapping inside individual AssetFirstLastSeenInfo and modern Entity returned properties are detailed in the following table:

Legacy field (AssetFirstLastSeenInfo message) Modern field (Entity message) Field type Parity and migration notes
asset (AssetIndicator) metadata.entity_type / attributes Message Mapped into standard Chronicle API Entity structures where metadata.entity_type is set to ASSET (or USER, DOMAIN_NAME).
first_seen_artifact_info first_seen_time Timestamp Mapped into first observed timestamps on the returned entity representation.
last_seen_artifact_info last_seen_time Timestamp Mapped into last observed timestamps on the returned entity representation.

Key differences

  • Service decoupling and graph generalization:
    • Legacy asset communication queries were housed under SearchService (ListArtifactAssets) and restricted strictly to asset indicators.
    • Modern Chronicle API generalizes graph traversal under EntityService (FindRelatedEntities), allowing clients to query any entity type (assets, users, domains, IPs) and filter results by relationship taxonomy (entity_types, domain_type).
  • Google Cloud project scoping integration:
    • Scoped natively under parent project instance folder bindings (instance path parameter).
  • Pagination and truncation handling:
    • Pagination (page_size, page_token, next_page_token) is retired and deprecated. Instead, clients control volume using limit (max 100) and check truncation status using has_more_entities.
  • Time window consolidation (Interval):
    • Standalone timestamp pairs are structured into standard google.type.Interval objects (time_range, result_time_range).
  • IAM permissions:
    • Request validation maps to standard Cloud IAM permission validation check (chronicle.googleapis.com/entities.findRelatedEntities).