# Tagging and Usage Tracking

Any request which affects your Key balance may be decorated with metadata called tags. This data is stored along with your lookup history and can be queried via the API. We call the ability to label your requests "tagging".

Tagging can be useful for recording the circumstances under which a request was made. For instance, you may use it to identify which of your servers, users or staff are performing requests with your key.

Tagged requests can be queried or downloaded at a later date via our API or the dashboard.

## Tag a Request[​](#tag-a-request "Direct link to Tag a Request")

For each property you can append a tag to your request using `tags=`. For instance, for webpage.co.uk you could append `tags=a`.

If you're using the HTTP API directly the request will go from:

```
/v1/autocomplete/addresses/paf_12345/gbr?api_key=ak_test
```

To this:

```
/v1/autocomplete/addresses/paf_12345/gbr?api_key=ak_test&tags=a
```

### Multiple Tags Example[​](#multiple-tags-example "Direct link to Multiple Tags Example")

Tagging is available across all methods which affect your lookup balance. To use multiple tags, include a comma separated list of tags in the query string of your URI:

```
/v1/autocomplete/addresses/usps_99382|2|32|9923/gbr?api_key=key&tags=app1,usa
```

## Track by Tag[​](#track-by-tag "Direct link to Track by Tag")

There are 2 ways to generate usage statistics:

1. Our daily usage statistics API
2. Our key usage CSV export API

Both are available on the dashboard. Click `Filter by Tags` and enter the tag (in this case `a`) to get back the usage:

![usage dashboard](https://img.ideal-postcodes.co.uk/usage-dashboard.jpeg)

The tag will appear in your CSV usage log in the second-to-last column. The final column records the number of lookups consumed by the transaction:

![usage excel](https://img.ideal-postcodes.co.uk/usage-tag.jpeg)

If you wish to do quite heavy analysis, we recommend outputting all your CSV usage without tag filtering. Then load the CSV into Excel and use Excel's `Filter` functionality to filter the tag column and do the analysis there.

## Notes[​](#notes "Direct link to Notes")

Tagging is only available via methods that drain your balance such as postcode or address search. Unsuccessful requests (i.e. non-2000 responses) do not affect your balance and so cannot be tagged.

You may query tagged requests via the `/keys` endpoint. The [Key usage API](/docs/api/key-usage.md) allows you to query for usage by tag. The [CSV lookup history API](/docs/api/key-logs.md) will also provide tag data with every request.

Tag storage and searching is also case sensitive.

## Restrictions[​](#restrictions "Direct link to Restrictions")

There are a small number of restrictions on what may be tagged:

* You may only specify up to 5 tags per API request
* Each tag must not be longer than 16 UTF-8 characters