---
title: "Detect and remove tracking pixels"
method: POST
path: "/security/detect-tracking"
tags: ["Security"]
---

# Detect and remove tracking pixels

`POST /security/detect-tracking`

## Request

- Base URL: `https://api.filegraph.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.filegraph.ai/security/detect-tracking`
- Auth: API key in header `X-API-Key`

Detect and optionally remove tracking pixels from HTML emails and documents.

## What Are Tracking Pixels?

Tracking pixels are invisible elements embedded in emails and documents to monitor:
- When and where the document is opened
- How many times it's viewed
- Geographic location and device information

## Detection Capabilities

### Known Tracking Services
Automatically identifies pixels from major email marketing and analytics platforms:
- **Email Marketing**: Mailchimp, SendGrid, HubSpot, ConvertKit, Mandrill, Mailgun
- **Social Media**: Facebook, LinkedIn, Twitter/X, Pinterest
- **Analytics**: Google Analytics, Bing, Quantcast, ComScore

### Detection Indicators
- **1x1 pixel dimensions** - Classic tracking pixel signature
- **Hidden elements** - CSS hiding (display:none, visibility:hidden, opacity:0)
- **Tracking URLs** - Paths containing /track/, /pixel/, /beacon/, /open/
- **Query parameters** - UTM parameters, subscriber IDs, campaign IDs
- **Encoded paths** - Long base64-encoded tracking identifiers

## Response

Returns a list of all detected tracking pixels with:
- URL and type (image, iframe, beacon)
- Confidence score (0.0 - 1.0)
- Known source identification (if recognized)
- Reasons why it was flagged

When `remove=true`, the response includes the cleaned file content.

## Example

```python
import httpx
import base64

# Detect tracking pixels
response = httpx.post(
    "https://api.filegraph.ai/security/detect-tracking",
    headers={"X-API-Key": "your-api-key"},
    files={"file": open("email.html", "rb")},
    data={"remove": "false"}
)

result = response.json()
print(f"Found {len(result['pixels_found'])} tracking pixels")

# Remove tracking pixels
response = httpx.post(
    "https://api.filegraph.ai/security/detect-tracking",
    headers={"X-API-Key": "your-api-key"},
    files={"file": open("email.html", "rb")},
    data={"remove": "true"}
)

result = response.json()
if result["was_modified"]:
    cleaned = base64.b64decode(result["content_base64"])
    with open("email_cleaned.html", "wb") as f:
        f.write(cleaned)
```

## Response `200`

Successful Response

- TrackingPixelResponse: Response for tracking pixel detection/removal operation.
  - `pixels_found` TrackingPixelInfo[], required: List of tracking pixels detected in the document
    - `url` string, required: URL of the tracking pixel
    - `type` 'image' | 'iframe' | 'beacon', required: Type of tracking pixel detected.
    - `source` string, nullable: Known tracker source if identified (e.g., 'mailchimp', 'facebook')
    - `location` string, required: Where in document the pixel was found (e.g., 'img[3]', 'iframe[0]')
    - `confidence` number, required: Detection confidence score from 0.0 to 1.0
    - `reasons` string[], required: List of reasons why this was flagged as a tracker
  - `pixels_removed` integer, required: Number of tracking pixels that were removed (0 if remove=false)
  - `document_type` string, required: Detected document type (e.g., 'text/html', 'message/rfc822')
  - `was_modified` boolean, required: Whether the document was modified (pixels were removed)
  - `filename` string, nullable: Output filename (only when modified)
  - `content_type` string, nullable: MIME type of the output file (only when modified)
  - `size_bytes` integer, nullable: Size of cleaned file in bytes (only when modified)
  - `content_base64` string, nullable: Base64-encoded cleaned file content (only when modified)

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/filegraph/apis/docconvert-api.md) · [All operations](https://skmtc.dev/filegraph/apis/docconvert-api/llms.txt) · [OpenAPI document](https://skmtc.dev/filegraph/apis/docconvert-api/revisions/436255c85bd4?raw)