---
id: tags-search
slug: /apis/tags/search
title: 'Search Tags'
description: 'Substring-match tag names with GET ~/api/tags/command/search?term=<term>.'
sidebar_label: 'Search Tags'
sidebar_position: 4
tags: ['api', 'tags', 'search']
---

Substring search over tag names. Use this to power a type-ahead, or to find the variants of a
tag you are about to [merge](/apis/tags/merge).

## Request

```text
GET ~/api/tags/command/search?term=<term>
```

| Parameter | In    | Required | Description                                    |
| --------- | ----- | -------- | ---------------------------------------------- |
| `term`    | query | yes      | Substring to match against tag names.          |

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

## Response

A flat JSON array of matching tag strings — **no counts**. If you need usage information for a
match, follow up with [query a tag](/apis/tags/query).

```json title="200 OK"
[
  "Automated SQL UnitTests",
  "ProductPlanning Regression Tests",
  "RegressionTestDetails",
  "RegressionTests",
  "Testboard",
  "TestSetDetails"
]
```

Note that the match is a **substring match anywhere in the name**, not a prefix match:
`Testboard` and `RegressionTestDetails` both matched `Test`.

## Notes

- Matching is case-insensitive.
- An empty result set is returned as `[]`, not a `404`.
- Despite living under the `/command/` path segment alongside `merge` and `remove`, search is a
  read-only `GET` and requires no special privilege.

## Related Topics

- [Query all tags](/apis/tags/query-all) — when you want the whole vocabulary with counts
- [Merge tags](/apis/tags/merge)
- [Tags overview](/apis/tags)