---
id: tags-query
slug: /apis/tags/query
title: 'Query a Tag'
description: 'Retrieve usage counts for a single tag with GET ~/api/tags?tag=<tag>.'
sidebar_label: 'Query a Tag'
sidebar_position: 2
tags: ['api', 'tags', 'query']
---

Returns usage information for one specified tag.

## Request

```text
GET ~/api/tags?tag=<tag>
```

| Parameter | In    | Required | Description                                                                                     |
| --------- | ----- | -------- | ----------------------------------------------------------------------------------------------- |
| `tag`     | query | yes      | The tag name to look up. URL-encode spaces and symbols.                                          |
| `field`   | query | no       | A custom tag attribute to look in instead of the standard `TaggedWith`. See [custom tag fields](#custom-tag-fields). |

```bash title="Request"
curl "https://{host}/{instance}/api/tags?tag=UX" \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/json"
```

## Response

```json title="200 OK"
{
  "tag": "UX",
  "colorName": "yellow500",
  "count": 1,
  "visibleCount": 1
}
```

| Field          | Type    | Meaning                                                                   |
| -------------- | ------- | ------------------------------------------------------------------------- |
| `tag`          | string  | The tag as stored, with its original casing.                              |
| `colorName`    | string  | The display colour assigned to the tag, e.g. `yellow500`. May be `null`.  |
| `count`        | integer | Total usages of the tag across the whole instance.                        |
| `visibleCount` | integer | Usages 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](/apis/tags#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`:

```json title="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:

```bash title="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.

:::note 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](/apis/tags/merge) and [remove](/apis/tags/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](/apis/tags/search) instead.

## Related Topics

- [Query all tags](/apis/tags/query-all)
- [Search tags](/apis/tags/search)
- [Tags overview](/apis/tags)