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

# Customize metadata

> Pass custom participant data via URL parameters

Custom metadata lets you attach information to each interview by adding parameters to your study link. Use it to identify users, track campaign sources, and segment your results.

## Adding metadata to your link

Append query parameters with the `meta_` prefix to your study URL. The prefix is stripped automatically, so `meta_source` becomes `source` in your dashboard.

```
https://pillow.so/abc123?meta_source=email&meta_campaign=q1-feedback
```

You can add as many parameters as you need:

```
https://pillow.so/abc123?meta_user_id=usr_123&meta_plan=pro&meta_source=email&meta_campaign=checkout-feedback
```

## Example use cases

### Track where interviews come from

```
https://pillow.so/abc123?meta_source=email&meta_campaign=q1-feedback
https://pillow.so/abc123?meta_source=in-app&meta_campaign=feature-launch
https://pillow.so/abc123?meta_source=support&meta_campaign=ticket-followup
```

### Segment by user attributes

```
https://pillow.so/abc123?meta_plan=enterprise&meta_role=admin
https://pillow.so/abc123?meta_plan=free&meta_account_age=new
```

### Link to your user database

```
https://pillow.so/abc123?meta_user_id=usr_abc123&meta_org_id=org_xyz789
```

## What Pillow captures automatically

Every interview automatically records system metadata, no URL parameters needed:

| Field      | Description                         | Example                         |
| ---------- | ----------------------------------- | ------------------------------- |
| Locale     | User's detected language            | `en-US`                         |
| Location   | Country, region, and city (from IP) | `US, California, San Francisco` |
| Device     | Device type                         | `desktop`                       |
| User-agent | Browser information                 | `Chrome 120 on macOS`           |

This appears alongside your custom metadata in the interview view.

## Viewing metadata

Open an interview and click the **Metadata** button in the footer bar. The panel shows:

* **Metadata**: Your custom `meta_` parameters
* **System**: Locale, location, device, and user-agent

## Filtering interviews by metadata

Click the filter icon in the interview list, then scroll to the **Metadata** section. Click **Add** to pick a metadata key, then select specific values to filter by.

This is where consistent naming pays off: if all your email campaigns use `meta_source=email`, you can filter to just those interviews in one click.

## Limits

| Constraint       | Limit          |
| ---------------- | -------------- |
| Max parameters   | 50             |
| Max key length   | 64 characters  |
| Max value length | 512 characters |

Keys can contain letters, numbers, underscores, dots, and dashes. Pillow truncates values that exceed the limit.

## Best practices

### Keep keys short and consistent

Use short, descriptive keys after the prefix:

* ✅ `meta_plan`, `meta_source`, `meta_user_id`
* ❌ `meta_user_subscription_plan_type`, `meta_marketing_campaign_source`

### Standardize values

Pick a casing convention and stick to it:

* ✅ `meta_plan=pro`, `meta_plan=free`, `meta_plan=enterprise`
* ❌ `meta_plan=Pro`, `meta_plan=FREE`, `meta_plan=Enterprise Plan`

### Avoid sensitive data

<Warning>
  **Never pass sensitive information in URLs.** URL parameters are visible in browser history, server logs, and analytics tools.

  Avoid: passwords, API keys, personal health information, financial data.
</Warning>

## FAQ

<AccordionGroup>
  <Accordion title="What if I shared links without metadata?">
    No problem. Interviews work normally, they just won't have custom tags. You can add metadata to future links without affecting existing interviews.
  </Accordion>

  <Accordion title="Can I add metadata after an interview starts?">
    No. Metadata is captured when the user first opens the link. You can't add or modify metadata for existing interviews.
  </Accordion>

  <Accordion title="Is there a limit to how many parameters I can add?">
    You can add up to 50 parameters per prefix. The total URL should stay under roughly 2,000 characters to avoid issues with email clients and messaging platforms.
  </Accordion>
</AccordionGroup>

## What's next

<CardGroup cols={2}>
  <Card title="Broadcast your study" icon="share" href="/guides/broadcast-study">
    Put your metadata-tagged links to work.
  </Card>

  <Card title="Review interviews" icon="eye" href="/guides/review-interviews">
    See metadata in the interview view.
  </Card>
</CardGroup>