---
title: Tags
description: Filter and run groups of reusable Tests by project tag.
---

# Tags

Tags group reusable Tests within a project. The public API can filter Tests by an existing tag and trigger the whole tagged group. Create, rename, assign, and remove tags in the Smoketest app.

Ticket-generated Tests do not join these reusable groups unless someone explicitly saves an independent reusable copy.

## List Tests with a tag

Pass both `projectId` and `tag` to `GET /v1/tests`:

```bash
curl "https://api.smoketest.sh/v1/tests?projectId=$PROJECT_ID&tag=Smoke" \
  -H "Authorization: Bearer $SMOKETEST_API_KEY"
```

The tag lookup is scoped to the project. A `tag` without `projectId` returns `400`.

## Run a tagged group

`POST /v1/tests/run` starts one Run for each reusable Test assigned to the tag:

```bash
curl -X POST https://api.smoketest.sh/v1/tests/run \
  -H "Authorization: Bearer $SMOKETEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "018e5678-abcd-7000-8000-abc123456789",
    "tag": "Smoke"
  }'
```

This requires the `run` scope. You can also pass `startUrl` to override the starting URL for every Run in that request.

If no Tests match the tag, the API returns `404` and creates no Runs.