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:
| Field | Description |
|---|---|
id | Unique group id: the tag name by default, the prefix when the value axis is off, qualified with @<location> when grouped by location. |
attributes.tag | The full tag name (namespace:value), or the prefix when the value axis is off. |
attributes.namespace | The requested prefix. |
attributes.value | The tag value (the part after the namespace); null when grouping by the whole prefix. |
attributes.asset_count | Number of member assets carrying the tag. |
attributes.asset_task_id | The ingestion task(s) the members were uploaded in β a string, or an array when several. |
attributes.location_id / attributes.location_type | Distinct location(s) across the members β a string, an array when several, or null. Only present when locations are resolved (see below). |
attributes.tags | Every tag name carried by any member, across all namespaces (not just the requested prefix). |
attributes.asset_data | Merged source data across the members (see below). |
attributes.truncated | true when the group had more members than the merge cap (1000). |
relationships.assets.data | The member assets β each with its own location_id / location_type and a link to /ingestions/assets/{id}. |
βΆHow asset_data merges
asset_data mergesasset_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)
/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=)
?group_by=)The group key is built from one or two axes, comma-separated. Default is
value.
group_by= | One group per⦠| value field | id |
|---|---|---|---|
value (default) | tag value | the value | partno:AB-100 |
value,location_id | tag value + location | the value | partno:AB-100@<loc> |
location_id | the whole prefix + location | null | partno@<loc> |
namespace | the whole prefix (single group) | null | partno |
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=trueaddslocation_id/location_typeto each group (distinct across members β scalar, array, ornull) and to each member.- Any
group_bythat includeslocation_idimplies 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
| Status | Code | Cause |
|---|---|---|
| 400 | VALIDATION_ERROR / BAD_REQUEST | :prefix contains a colon/whitespace or normalises to empty; or filter[organization_id] outside your scope. |
| 401 | MISSING_API_KEY / INVALID_API_KEY | Auth missing or invalid. |
| 403 | FORBIDDEN | API key lacks ingestions:read. |
Required scope:
ingestions:read