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

# Tag Requests for Usage Reporting

> Attach caller-defined tags to any Context.dev API request so you can filter and attribute credit usage by environment, team, or feature on the dashboard.

Every non-monitor endpoint accepts an optional `tags` input that gets recorded on the request's usage log. Tags are yours to define — common uses are environment (`production`, `staging`), team or tenant (`team-alpha`, `customer-42`), or feature (`onboarding-flow`, `nightly-refresh`). You can then filter the usage tab of your [dashboard](https://www.context.dev/dashboard) by any tag to see credits burned by that slice.

Tags are purely for observability. They don't change response shape, pricing, caching, or rate limits.

## When to use tags

Reach for tags when a single API key serves multiple workloads and you need to see which one is spending credits:

* Split spend between `production` and `staging` on the same key.
* Attribute usage to internal teams, tenants, or customers.
* Compare cost of one code path (say, `nightly-batch`) against another (`user-triggered`).
* Track cost of an experiment or migration before you commit.

If everything on the key is one workload, you don't need tags.

## How to send tags

Tags are optional on every endpoint except `/v1/monitors/*` and `/v1/admin/*`. On monitors, `tags` keeps its existing meaning — tags belong to the monitor resource itself, and every run of a tagged monitor automatically carries those tags to its usage log.

The shape depends on the HTTP method:

| Request type               | Where tags go            | Format                                              |
| -------------------------- | ------------------------ | --------------------------------------------------- |
| `POST` (JSON body)         | `tags` field in the body | Array of strings                                    |
| `GET` and `POST /v1/parse` | `tags` query parameter   | Comma-separated string, or repeated `?tags=` params |

Limits (same as monitor tags):

* Up to **20 tags** per request.
* Each tag is **1–50 characters**.
* Duplicates across body and query are deduplicated.
* Invalid tags return `400 INPUT_VALIDATION_ERROR`.

### POST example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.context.dev/v1/brand/retrieve \
    -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "by_domain",
      "domain": "stripe.com",
      "tags": ["production", "team-alpha"]
    }'
  ```

  ```typescript TypeScript theme={null}
  const { brand } = await client.brand.retrieve({
    type: "by_domain",
    domain: "stripe.com",
    tags: ["production", "team-alpha"],
  });
  ```

  ```python Python theme={null}
  brand = client.brand.retrieve(
      type="by_domain",
      domain="stripe.com",
      tags=["production", "team-alpha"],
  )
  ```
</CodeGroup>

### GET example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.context.dev/v1/web/scrape/markdown?url=https://example.com&tags=production,team-alpha" \
    -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"
  ```

  ```bash Repeated params theme={null}
  curl "https://api.context.dev/v1/web/scrape/markdown?url=https://example.com&tags=production&tags=team-alpha" \
    -H "Authorization: Bearer $CONTEXT_DEV_API_KEY"
  ```
</CodeGroup>

## Filter usage by tag

Once a tagged request is logged, open the usage tab of your [dashboard](https://www.context.dev/dashboard) and filter by any tag to see the credits and request count attributed to that slice. Monitor runs on a monitor that has resource-level `tags` also appear under those tags, so you can view monitor and non-monitor spend side by side.

## Related

* [Handle Rate Limits](/optimization/rate-limits) — pace requests once you've identified which tag is burning quota.
* [Integration Best Practices](/optimization/best-practices) — patterns to keep spend predictable.