Skip to main content

Query a Tag

Returns usage information for one specified tag.

Request​

GET ~/api/tags?tag=<tag>
ParameterInRequiredDescription
tagqueryyesThe tag name to look up. URL-encode spaces and symbols.
fieldquerynoA custom tag attribute to look in instead of the standard TaggedWith. See custom tag fields.
Request
curl "https://{host}/{instance}/api/tags?tag=UX" \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/json"

Response​

200 OK
{
  "tag": "UX",
  "colorName": "yellow500",
  "count": 1,
  "visibleCount": 1
}
FieldTypeMeaning
tagstringThe tag as stored, with its original casing.
colorNamestringThe display colour assigned to the tag, e.g. yellow500. May be null.
countintegerTotal usages of the tag across the whole instance.
visibleCountintegerUsages on assets the calling member can see.

count and visibleCount diverging is the normal case for a project-scoped member, not an error. See scope visibility.

Tag Not Found​

An unknown tag returns 404 Not Found, not a zero-count object. The body is the same shape with an added message:

404 Not Found
{
  "tag": null,
  "count": 0,
  "visibleCount": 0,
  "message": "Tag not found"
}

The message is localized, so do not match on its text — check the status code.

Custom Tag Fields​

By default this endpoint reads the standard TaggedWith attribute shared by all tagged assets. Instances that define custom tag-typed attributes can target one with the field parameter, passing the attribute definition token:

Query a custom tag field on Story
curl "https://{host}/{instance}/api/tags?tag=cTag1&field=Story.Custom_cTagStory" \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/json"

Omitting field — the normal case — reads the standard tag attribute across all asset types.

Undocumented in the original reference

The field parameter and the colorName response field were both absent from the published reference material. field is also accepted by merge and remove.

Notes​

  • Tag matching is not case-sensitive, but the tag value in the response echoes the stored casing. Query ux and you may get "tag": "UX" back.
  • To find tags when you only know part of the name, use search instead.