Group Assets By Tag Prefix

Group the assets you have ingested by the namespaced tags they carry, and get back a merged view of each group's data β€” answering "across every row tagged with this part / SKU / batch, what do I know?" directly off the ingestion layer, before any metrics run.

Tags follow a namespace:value convention (e.g. partno:AB-100). Given a namespace as the :prefix path segment, this endpoint returns one group per distinct prefix:value tag in your organization by default:

GET /ingestions/assets/groups/partno

You can change what a group represents β€” group by the whole prefix and/or by location β€” with ?group_by=.

What a group contains

Each asset_group resource carries:

FieldDescription
idUnique group id: the tag name by default, the prefix when the value axis is off, qualified with @<location> when grouped by location.
attributes.tagThe full tag name (namespace:value), or the prefix when the value axis is off.
attributes.namespaceThe requested prefix.
attributes.valueThe tag value (the part after the namespace); null when grouping by the whole prefix.
attributes.asset_countNumber of member assets carrying the tag.
attributes.asset_task_idThe ingestion task(s) the members were uploaded in β€” a string, or an array when several.
attributes.location_id / attributes.location_typeDistinct location(s) across the members β€” a string, an array when several, or null. Only present when locations are resolved (see below).
attributes.tagsEvery tag name carried by any member, across all namespaces (not just the requested prefix).
attributes.asset_dataMerged source data across the members (see below).
attributes.truncatedtrue when the group had more members than the merge cap (1000).
relationships.assets.dataThe member assets β€” each with its own location_id / location_type and a link to /ingestions/assets/{id}.

How asset_data merges

asset_data is the union of the members' source columns, collapsed column-by-column:

  • a column every member agrees on β†’ a single scalar value;
  • a column members disagree on β†’ the array of its distinct values;
  • a column present on only some members is still included.

In the example, two assets are tagged partno:AB-100. They share COUNTRY: "MY" (β†’ scalar) but differ on NAME (β†’ ["Refinery Alpha", "Mill Beta"]), and only one carries CITY (β†’ "Medan").

Why this and not one row per asset? Assets are deduplicated by a hash of their full source, so two uploads only share an asset when their data is identical. Merging happens across the distinct assets that share a tag β€” that's the level a sourcing question is asked at.

Why a dedicated endpoint (vs /locations/groups)

Tags are anchored on the asset entity at ingest time (including the per-row namespace:{Column} tag templates you supply on upload). They only reach the location layer (/locations/groups/:prefix) after a metrics/stats run promotes the asset to a facility / shed / plot. This endpoint reads the asset tags directly, so a metric-less upload (terminal status staged) is groupable immediately β€” no promotion required.

Choosing the group key (?group_by=)

The group key is built from one or two axes, comma-separated. Default is value.

group_by=One group per…value fieldid
value (default)tag valuethe valuepartno:AB-100
value,location_idtag value + locationthe valuepartno:AB-100@<loc>
location_idthe whole prefix + locationnullpartno@<loc>
namespacethe whole prefix (single group)nullpartno

Group by prefix & location β€” drop value from the key so every asset carrying any tag in the namespace is grouped by location alone:

GET /ingestions/assets/groups/partno?group_by=location_id

gives one group per location (partno@<location_id>, or partno@none for members with no validated location), each merging all assets tagged under partno at that location. When the value axis is off, attributes.value is null and attributes.tag is the prefix itself.

Each location-qualified group's merge is over just the members at that location; a member's location is the first location any of its uploads validated into.

Resolving locations (optional)

Resolving locations adds a staged_location join, so it is opt-in:

  • ?include_location=true adds location_id / location_type to each group (distinct across members β€” scalar, array, or null) and to each member.
  • Any group_by that includes location_id implies it.
  • Otherwise the location fields are omitted and the join is skipped.

The prefix

The :prefix is the namespace only β€” it must be colon-free (word characters and hyphens). It is normalised to lowercase snake_case to match how tag namespaces are stored (so Part-No resolves to part_no). A prefix containing a colon, or one that normalises to empty, returns 400.

Narrowing to specific tags

Pass ?filter[tags]= to restrict to specific tag names within the prefix:

GET /ingestions/assets/groups/partno?filter[tags]=in:partno:AB-100,partno:CD-200

Pagination & ordering

Groups are paged with ?page / ?page_size, ordered by tag value. A group is never split across pages. meta.total is the number of matching groups (capped; meta.total_is_approx is true when the cap is exceeded β€” pass ?meta[count]=exact to force an unbounded count).

Org scoping

Groups and their members are scoped to your effective organizations. A tag value present in both a parent and a child org merges into one group with its members (and their data) combined; assets outside your scope never appear.

Errors

StatusCodeCause
400VALIDATION_ERROR / BAD_REQUEST:prefix contains a colon/whitespace or normalises to empty; or filter[organization_id] outside your scope.
401MISSING_API_KEY / INVALID_API_KEYAuth missing or invalid.
403FORBIDDENAPI key lacks ingestions:read.

Required scope: ingestions:read