Docs/Core Concepts/Tags

Tags

Tags are hierarchical labels you can attach to instruments and time series types to organize and filter your data. Tags are workspace-scoped, nestable, and queryable.

Tag hierarchy

Tags form a tree. A tag can have a parent (another tag), making it a child or descendant. The path from root to a tag is expressed using #-delimited slugs:

Tag path syntax

# Root tag
#equity

# Child: US Equities under equity
#equity#us

# Grandchild: Large Cap under US Equities
#equity#us#large-cap

Tag paths are used in filter queries and bulk assignment requests. You can reference any tag by its UUID, slug (for root tags), or full path.

Assigning tags to instruments

Tags are assigned to instruments via the /instruments/{instrumentId}/tags endpoints. An instrument can have any number of tags, and a tag can be assigned to any number of instruments.

Add a single tag

POST /instruments/{instrumentId}/tags with the tag UUID or path in the body.

Bulk replace all tags

PUT /instruments/{instrumentId}/tags with an array of tag identifiers to atomically replace all assignments.

Bulk replace tags

PUT /v1/workspaces/acme-capital/instruments/bhp.ax/tags

["equity", "#equity#aus", "3fa85f64-5717-4562-b3fc-2c963f66afa6"]

Filtering by tags

The filter API supports two tag operators for instruments:

tagged

Matches instruments tagged with exactly the specified tag. Does not include instruments tagged with descendants.

tagged_with_descendants

Matches instruments tagged with the specified tag or any descendant. Use this for broad category queries.

Filter: all ASX equities under the #equity tree

{
  "filter": {
    "and": [
      { "field": "tags", "op": "tagged_with_descendants", "value": "#equity" },
      { "field": "field.exchange", "op": "eq", "value": "ASX" }
    }
  }
}

Archiving tags

Archiving a tag also archives all of its descendants. Archived tags cannot be assigned to instruments — attempts return 422 Unprocessable Entity. Existing assignments to archived tags are preserved but the instruments are no longer considered “tagged” for filter purposes.

Archiving a parent tag archives the entire subtree. Restoring only restores the specific tag — descendants must be restored individually.

Time series tags

Time series types support the same tag system as instruments, using a parallel set of /time-series-tags endpoints. The same hierarchy, assignment, and filter semantics apply. Time series tags are useful for grouping related series (e.g. all pricing series vs. all volume series).