Skip to content

Tags

A tag is a tracked object — usually a piece of equipment, a vehicle, or a worker — whose location the RTLS reports on. Tags are the highest-volume entity in most deployments. (The server's underlying wire resource is named trackable_objects; the SDK uses "tag" in prose and parameter names alike.)

Quick reference

Method What it does
client.tags.list(*, include_removed=False, company_scope=False) List all tags in scope.
client.tags.get(uid) Fetch one tag by uid.
client.tags.create(name, *, attached_zone=None, groups=None, **fields) Create a tag; optional zone-attach and group-bind in one call.
client.tags.update(uid, *, attached_zone=None, groups=None, **fields) Update with diff-driven zone / group reconciliation.
client.tags.delete(target) Delete one tag (uid / Tag) or many (list — returns BulkResult).
client.tags.bulk_update(tag_uids, changes) Apply the same change-set to N tags, continue-on-error.
client.tags.list_active_for_period(start, end) Tags with positions in the window.
client.tags.list_active_in_period(sublocation_uid, start, end) Active in window AND in this sublocation.
client.tags.list_existed_for_period(start, end) Tags that existed in the window (whether active or not).
client.tags.list_templates() Tag templates available in this deployment.
client.tags.last_position(uid) Most recent Position for a tag, or None.
client.tags.replace_groups(uid, group_uids, *, no_notify=True) Replace the tag's group memberships with a bare list.
client.tags.create_raw / update_raw / delete_raw Single-call REST escape hatches. See raw REST methods.

Reading

Listing returns list[Tag]. Filter variants for time windows:

tags = client.tags.list()                                    # all in scope
recent = client.tags.list_active_for_period(start, end)      # had positions
in_bay = client.tags.list_active_in_period(area.uid, start, end)

Fetching one (client.tags.get(uid)) returns Tag or raises NotFound.

Writing

The create compound creates the tag, optionally creates a dynamic zone bound to it, and optionally binds groups — in one call, with rollback on partial failure:

tag = client.tags.create(
    name="Forklift 9",
    attached_zone={"shape": "circle", "geometry": {"radius": 3000}},
    groups=["g-fleet", "g-priority"],
)

On partial failure the SDK rolls back the created tag and raises PartialFailureError — see compound workflows.

Tags don't carry a MAC address. The server's createTrackObject schema has no mac_address field — passing one is a silent no-op. To bind hardware to a tag, call client.nodes.create("aabbccddeeff") and client.tag_associations.create("aabbccddeeff", tag.uid) separately. See Associations and Nodes.

update is diff-driven: only fields you pass are sent. delete accepts a single uid, a Tag instance, or a list (which returns a BulkResult):

client.tags.delete(["t-1", "t-2", "t-3"])

For exact REST control without compound logic, use create_raw / update_raw / delete_raw. See raw REST methods.

Bulk operations

result = client.tags.bulk_update(
    tag_uids=["t-1", "t-2", "t-3"],
    changes={"description": "EOL"},
)
print(f"{len(result.successes)} updated, {len(result.failures)} failed")

BulkResult continues on error and reports which items raised.

Model — Tag

Field Type Notes
uid str Server-assigned.
name str \| None Display name.
mac_address str \| None Joined display field from the bound node (bare 12-hex); not set on create.
description str \| None Free-form.
self_zone_uid str \| None Dynamic zone bound to this tag, if any.
groups list[str] Group uids the tag belongs to.
template_uid str \| None Source template, if created from one.
removed_at datetime \| None Set on soft-delete.

Full field list for less-common attributes.

  • Attached zone: a tag can own a dynamic Zone via self_zone_uid. tags.create(attached_zone=...) and tags.delete keep the binding consistent.
  • Groups: a tag's Groups membership is managed via tags.create(groups=...), tags.update(groups=...), or tags.replace_groups.
  • Positions: tags.last_position(uid) returns the most recent location. For history, use Events.

See also