> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run tag-filtered scenarios

> Run active scenarios by tag from the web app, scheduler, webhook, CLI, or CI pipeline.

# Run tag-filtered scenarios

Tags let you run meaningful subsets of your suite. A `smoke` tag can gate deploys, a `regression` tag can run nightly, and a `security` tag can keep attack checks separate from everyday functional tests.

The same tag logic works from the web app, schedules, webhooks, CI, and the CLI.

## How tags work

Tags are project-scoped strings on scenarios and scenario groups. When you run by tag, Qodex picks up active standalone scenarios whose tags overlap the selected set.

Groups are included when the group's own tags match or when any member scenario's tags match. When a group matches, Qodex runs the whole group as one unit so ordered flows and folder-level context stay intact.

Common tags:

* `smoke` for fast checks after deploy.
* `regression` for broader scheduled coverage.
* `security` for OWASP and auth-related checks.
* `critical` for must-pass business flows.

Multiple tags use OR semantics. A scenario tagged with any selected tag is included.

## Run from the web app

Open **Scenarios**, apply the **Tags** filter, then click **Run all**. Qodex runs every matching active scenario, not only the visible page of rows.

Use bulk actions to add tags to many scenarios at once.

## Run from a webhook

```bash theme={null}
curl -X POST \
  https://agents.qodex.ai/api/projects/my-project-slug/webhooks/trigger \
  -H "Authorization: Bearer qk_xxx..." \
  -H "Content-Type: application/json" \
  -d '{"environment":"staging","tags":["smoke"]}'
```

This is the common CI shape for smoke and critical checks.

## Run on a schedule

Create a schedule with run type **Tagged**, then choose the tags. The scheduler resolves the tag set at run time, so newly tagged active scenarios are picked up automatically.

## What gets skipped

* Draft scenarios are skipped on scheduled and webhook-triggered tagged runs.
* Unrunnable scenarios are skipped before execution.
* Empty tag results return an error or mark the schedule as skipped, depending on the trigger.

## Related

<CardGroup cols={2}>
  <Card title="Run the full suite" icon="list-checks" href="/run-tests-full-suite">
    Run everything active when tags are not enough.
  </Card>

  <Card title="Run tests in CI" icon="git-branch" href="/run-tests-in-ci">
    Use tagged runs as required pipeline checks.
  </Card>

  <Card title="Test groups and folders" icon="folder" href="/run-tests-test-groups-and-folders">
    Understand how group tags and member tags affect runs.
  </Card>
</CardGroup>