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

# Update pixels

> Attach tracking pixels and choose when in playback they fire.

Pixels fire tracking events as the video plays. `items` is a collection, so the
merge works per item: an item **with an `id`** patches that pixel, an item
**without one** creates a new pixel, and an item with `"_destroy": true`
deletes it. Pixels you don't mention stay as they are.

This is a [merge-patch](/guides/merge-patch): send only the keys you want to
change and everything else keeps its stored value.

## Fire a custom pixel at 50%

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://api.vturb.com/v1/videos/{id} \
    -H "Authorization: Bearer vt_..." \
    -H "Content-Type: application/json" \
    -d '{ "pixels": { "enabled": true, "items": [
          { "base": { "name": "Half-view", "type": "custom" },
            "tag": { "html": "<script>track()</script>" },
            "dispatch": { "active": true, "mode": "percent", "threshold": 50 } }
        ] } }'
  ```

  ```json Body theme={null}
  {
    "pixels": {
      "enabled": true,
      "items": [
        {
          "base": { "name": "Half-view", "type": "custom" },
          "tag": { "html": "<script>track()</script>" },
          "dispatch": { "active": true, "mode": "percent", "threshold": 50 }
        }
      ]
    }
  }
  ```
</CodeGroup>

## The keys

| Key                          | Type    | Writes                                                      |
| ---------------------------- | ------- | ----------------------------------------------------------- |
| `enabled`                    | boolean | Master switch for all pixels                                |
| `items[].id`                 | string  | Targets an existing pixel; omit to create one               |
| `items[]._destroy`           | boolean | `true` deletes the pixel the `id` points to                 |
| `items[].base.name`          | string  | Internal label of the pixel                                 |
| `items[].base.type`          | string  | `facebook`, `google` or `custom`                            |
| `items[].tag.html`           | string  | The HTML/JS snippet a `custom` pixel injects                |
| `items[].dispatch.active`    | boolean | Turns firing on or off for this pixel                       |
| `items[].dispatch.mode`      | string  | `percent` (of the video watched) or `time` (seconds played) |
| `items[].dispatch.threshold` | integer | The percent or second at which the pixel fires              |