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

# Changelog

> Track changes, new features, and improvements to the Cometly API.

## MCP v2.6.5

### November 5, 2026

**[`get_subscription_last_run`](https://docs.cometly.com/mcp/tools/get-subscription-last-run) now says it returns the subscription's configuration and last send time.** The description no longer implies it returns the digest's contents, which are not stored; `run_saved_report` runs the same report for its current results. There is no change to inputs or outputs.

***

## MCP v2.6.4

### November 5, 2026

**[`query_ad_metrics`](https://docs.cometly.com/mcp/tools/query-ad-metrics) now only states what each revenue figure is.** The description says what Reported Revenue, Reported Purchases, Gross Revenue, and Purchases each measure, and asks the model to label which set a figure comes from when it presents it. There is no change to inputs or outputs.

***

## MCP v2.6.3

### November 4, 2026

**[`query_ad_metrics`](https://docs.cometly.com/mcp/tools/query-ad-metrics) now describes platform-reported and Cometly-tracked revenue neutrally.** Reported Revenue and Reported Purchases are explained as the figures the ad platform reports, and Gross Revenue and Purchases as the conversions Cometly tracked. There is no change to inputs or outputs.

***

## MCP v2.6.2

### October 30, 2026

**Ad account connection and sync status are now accurate over MCP.** Disconnected ad accounts are no longer reported as connected, and `last_synced_at` is the last successful sync.

* [`get_workspace_context`](https://docs.cometly.com/mcp/tools/get-workspace-context) and [`list_ad_accounts`](https://docs.cometly.com/mcp/tools/list-ad-accounts) now return only ad accounts that are actively connected to the Space. Accounts you disconnected are left out.
* `last_synced_at` is now the time of the account's last successful sync. It used to be the time the account record was last changed, so an account whose sync was failing could look freshly synced. It is `null` until the account's first sync: an empty field in `list_ad_accounts` CSV rows, and left out of its JSON rows. For Google, LinkedIn, and TikTok accounts it stays empty until the first sync after this release.
* The `# hint:` footer on analytics tools now says `No <source> account is connected to this space` when the only accounts for that source are disconnected.
* The `<source> data may be incomplete` hint now appears when the most recent successful sync among a source's connected accounts is a day or more old. It had stopped appearing in July 2026.

***

## MCP v2.6.1

### October 30, 2026

**[`list_ads`](https://docs.cometly.com/mcp/tools/list-ads) now applies `limit` to the sources you ask for.** Previously the limit was split across every ad source even when you passed `sources`, so `sources: ["facebook_ads"]` with the default `limit` of 200 returned at most 28 rows. The limit is now split only across the sources returned, so a single-source call can return up to the full `limit`. The response also never exceeds `limit`, even when you ask for more sources than `limit` rows.

**[`inspect_site`](https://docs.cometly.com/mcp/tools/inspect-site) now detects OpenAI's Measurement Pixel (ChatGPT Ads).** It appears in `detection.ad_pixels[]` as `platform: "chatgpt"`, with its pixel id.

***

## MCP v2.6.0

### October 23, 2026

**One MCP URL for every Space** — add `https://app.cometly.com/mcp` to Claude, ChatGPT, Cursor, or any other client. The Space is no longer part of the URL.

* You choose what the connection covers on the Cometly consent screen. A single Space is shown directly; if you belong to several, choose **All my spaces** (every Space you belong to, including ones you're added to later) or **Choose spaces** (tick the ones to include), and pick a **default Space**. There's no Space ID to find or paste.
* The grant is in the token's ability: `mcp_space:42` (one Space), `mcp_space:42,7,9` (chosen Spaces, the first is the default), or `mcp_space:42,*` (all your Spaces), each optionally ending in `:read`. Membership, your role in the Space, and the team's plan are re-checked on every call for the Space it targets, so an all-Spaces connection follows your memberships. If your roles differ across Spaces, the token has full access and each call is allowed or refused by your role in the target Space.
* Every tool now accepts an optional `space_id` (the numeric ID from [`list_my_spaces`](https://docs.cometly.com/mcp/tools/list-my-spaces)). Without it the call runs in the default Space; a `space_id` the connection doesn't cover returns an authorization error asking you to reconnect and include it. Custom field and event labels in tool descriptions describe the default Space.
* [`list_my_spaces`](https://docs.cometly.com/mcp/tools/list-my-spaces) now returns `id,name,team,granted,default`. `granted` marks the Spaces this connection may use and `default` the one tools run in without `space_id`. The `current` column is gone.
* **Settings → Integrations → MCP** lists a multi-Space token on every Space it covers, with an **All spaces** or **N spaces** badge. Revoking it from any Space revokes it everywhere. Token names now read `MCP: Claude (Acme Marketing)`, `MCP: Claude (Acme Marketing +2)`, or `MCP: Claude (All spaces)`. Personal access tokens generated on that page are still single-Space.
* `https://app.cometly.com/mcp/{space_id}/public-api` still works as a legacy alias, so existing connections and configs need no change. The token's grant must cover the Space in the path, otherwise the call is refused with an `[authorization_error]` tool result.
* `https://app.cometly.com/mcp/chatgpt` is the same server, but `initialize`, `ping`, `tools/list`, and `notifications/initialized` are answered without a credential so the ChatGPT Apps directory can list the tools. Every other call needs a token. Use it as the server URL when you add Cometly to ChatGPT as a custom connector; the in-app ChatGPT guide shows it.

**Every Space member can connect** — MCP access no longer requires an Administrator with Use Public API permission. Membership in the Space is the gate.

* Viewers (members whose role has no permissions) get a read-only connection. The consent screen says so, and the write tools `update_contact`, `update_company`, and [`update_event`](https://docs.cometly.com/mcp/tools/update-event) are hidden from `tools/list` and refused for as long as the role is Viewer. The role is read live, so a promotion applies on the next call without reconnecting; only a headless token a Viewer generates carries `mcp_space:{id}:read` for life.
* A Viewer's connection also leaves out the contact and company tools ([`list_contacts`](https://docs.cometly.com/mcp/tools/list-contacts), [`get_contact`](https://docs.cometly.com/mcp/tools/get-contact), [`get_contact_journey`](https://docs.cometly.com/mcp/tools/get-contact-journey), [`query_contacts_aggregated`](https://docs.cometly.com/mcp/tools/query-contacts-aggregated), [`list_companies`](https://docs.cometly.com/mcp/tools/list-companies), `get_company`, `get_company_journey`), and [`search_workspace`](https://docs.cometly.com/mcp/tools/search-workspace) skips contacts and companies for them. The app hides those pages from Viewers (`space:see_journeys`), and MCP follows: a role sees the same data over MCP as in the app.
* Every other role gets full access. The role is re-checked on every write call, so a member demoted to Viewer loses the write tools immediately. Removal from the Space still revokes everything.
* Every member can generate personal access tokens on **Settings → Integrations → MCP**. A Viewer's tokens are always read-only (the **Read-only** checkbox is shown checked and locked).
* OAuth-connected clients are no longer always full access: they follow the user's role.

**OAuth discovery and tool metadata**

* `/.well-known/oauth-authorization-server` now returns `"token_endpoint_auth_methods_supported": ["none"]`. Protected-resource documents return `"bearer_methods_supported": ["header"]`, and the root `/.well-known/oauth-protected-resource` describes `https://app.cometly.com/mcp`.
* The `resource` parameter on `/mcp/oauth/authorize` is now optional. When present, it must be one of Cometly's MCP URLs.
* The 401 challenge on the server URL carries `WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://app.cometly.com/.well-known/oauth-protected-resource/mcp"`.
* Browser requests are origin-checked. Hosted clients send no origin; claude.ai, claude.com, chatgpt.com, chat.openai.com, platform.openai.com, and loopback addresses get CORS headers, and any other origin gets `403` `forbidden_origin`.
* Every tool now has a `title` and the `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` annotations. Read tools are read-only, idempotent, and closed-world. `update_*` tools are destructive and idempotent (collections you send replace the existing ones). [`inspect_site`](https://docs.cometly.com/mcp/tools/inspect-site) is open-world because it fetches your site. [`analyze_report`](https://docs.cometly.com/mcp/tools/analyze-report) is non-read-only and non-idempotent because it deducts AI credits.
* The token response `scope` stays `mcp:use`; the Space is on the token's ability. Tokens still don't expire and there is no refresh token.

See [Authentication](https://docs.cometly.com/mcp/authentication.md) for details.

***

## MCP v2.5.0

### October 21, 2026

**`inspect_site` sees pixels a tag manager injects** — when a browser renderer is configured, [`inspect_site`](https://docs.cometly.com/mcp/tools/inspect-site) now also loads the final page once in a real headless browser and merges the ad pixels that actually fired into the report.

* `detection.scan_method` is always present: `browser` when the browser pass ran, `static` otherwise.
* Every `detection.ad_pixels[]` entry gains `platform` (`facebook`, `google`, `tiktok`, `linkedin`, `bing`, `x`, `reddit`, `pinterest`, `snapchat`, `quora`, or `null`).
* Pixels the browser found carry `via: "browser"` and `matched_by` values prefixed `browser:`. A vendor seen in both the page source and the browser has `via: "both"` and lists both reasons.
* `detection.tag_managers` gains a `Google Tag Manager` entry when the page source showed none but the browser initialised one.
* A new top-level `browser_scan` block is `null` when no browser pass ran, otherwise `{ final_url, requests, elapsed_ms, error }`.
* Tags that wait for consent and never fire on load are still not visible. Without a renderer configured, only `scan_method: "static"` and `platform` are new.

**Business profile in workspace context** — [`get_workspace_context`](https://docs.cometly.com/mcp/tools/get-workspace-context) now returns a `business` object describing the company.

* `business` is `null` until setup step 1 ("About your business") has been saved. After that it contains `summary`, `type` (`ecommerce`, `saas`, `lead_gen`, `services`, or `other`), `website`, `platform`, `lead_destination`, `uses_native_lead_forms`, and `ad_platforms`.
* `summary` is up to three sentences on what the company sells, to whom, and how a customer converts. It is drafted from the website and editable in **Setup → step 1**.
* Existing fields are unchanged.

***

## MCP v2.4.0

### October 15, 2026

**MCP read-only tokens** — when you generate an MCP access token under **Settings → Integrations → MCP**, you can now tick **Read-only**.

* A read-only token carries the ability `mcp_space:{id}:read` instead of `mcp_space:{id}`. The write tools `update_contact`, `update_company`, and [`update_event`](https://docs.cometly.com/mcp/tools/update-event) are hidden from `tools/list`, and calling one returns a "Tool not found" error. Every other tool, resource, and prompt works the same.
* Read-only tokens show a **Read-only** badge in the token list, count toward the same 25-token limit, and are revoked the same way.
* Existing tokens keep full access, and a token can't be converted — generate a new read-only one. OAuth-connected clients are unchanged and always get full access.

See [Authentication](https://docs.cometly.com/mcp/authentication.md#read-only-tokens) for details.

***

## v1.5.0

### October 16, 2026

**All ids are returned as strings** — every `id`, `*_id`, and `*_ids` value in every API response and [export file](https://docs.cometly.com/concepts/exports-vs-pagination.md) is now a JSON string.

* Ids can exceed 2^53, and JavaScript clients rounded them when they were returned as numbers.
* Events already documented string ids and now return them. Contacts and Companies ids were documented as integers and are now strings, including `export_id`, `company_id`, `contact_id`, `contact_ids`, and `conflicting_company_id`.
* Path and body parameters accept ids as before.
* MCP tool outputs are unchanged.

***

## v1.4.1

### September 29, 2026

**Contacts dataset: `tracking_ids` column** — the [Contacts dataset](https://docs.cometly.com/data-warehouse/datasets/contacts.md) has a new optional column, `tracking_ids`.

* `tracking_ids` is an uncapped JSON array of strings: every distinct `tracking_id` sent on the contact's events, including values inherited from contacts merged into it. It's `[]` when none, and off by default.
* It sits in the Identity graph group, next to `emails`, `phones`, and `comet_tokens`.
* Existing exports are unaffected. Create a new Contacts export with the column enabled to get it.

***

## v1.4.0

### September 23, 2026

**New endpoint: Update Event** — [`PUT /events/{id}`](https://docs.cometly.com/api-reference/endpoint/update-event) updates fields on an already-ingested event using sparse PUT semantics.

* `amount` is the updatable field today: `number | null`, `>= 0`; numeric strings like `"120.25"` are accepted, and `null` clears the amount. At least one updatable field must be provided.
* Returns `200` with `{ "message": "Event updated successfully" }`, and `404` when the id does not exist in the caller's Space.
* Rate limited at **60 requests per minute** per Space, the same bucket as [Update Contact](https://docs.cometly.com/api-reference/endpoint/update-contact.md) and [Update Company](https://docs.cometly.com/api-reference/endpoint/update-company.md).
* New MCP tool [`update_event`](https://docs.cometly.com/mcp/tools/update-event) mirrors the endpoint. It requires `amount` and cannot clear it to `null`.

***

## v1.3.0

### September 9, 2026

**Company external ID on Create Event** — [`POST /events/track`](https://docs.cometly.com/api-reference/endpoint/create-event) now accepts two new optional fields: `company_external_id` and `company_name`.

* `company_external_id` groups this contact into a company using your own account or company identifier. It's trimmed, case-preserved (never lowercased), and stored byte-exact — 1 to 190 characters after trimming. Floats, arrays, and booleans are rejected with a `422`.
* `company_name` is a display name for the company identified by `company_external_id` — 1 to 255 characters after trimming, same type and validation rules. Last write wins, and it's never used for matching: two companies with the same name stay separate. It's ignored when `company_external_id` isn't also sent.
* Blank strings for either field are treated as absent (`null`).
* This is unrelated to `tracking_id`: `tracking_id` merges events into a single contact and never groups companies, while `company_external_id` groups contacts into a company and never merges contacts or takes part in contact matching. Never send a shared account ID as `tracking_id`.
* `company_external_id` is only honored when the Space's company identity mode is set to **External ID** in Space Settings. In the default **Auto** mode (companies grouped by business-email domain), the value is accepted and stored but ignored for grouping.

**Company `external_id` on the Companies API** — [Get Company](https://docs.cometly.com/api-reference/endpoint/get-company.md), [List Companies](https://docs.cometly.com/api-reference/endpoint/list-companies.md), and [Update Company](https://docs.cometly.com/api-reference/endpoint/update-company.md) now expose `external_id`, the customer-supplied external ID counterpart to `domain`.

* `external_id` is an identifier, not just a label: it decides which company future events carrying that `company_external_id` are matched to, the same way `domain` decides matching by email domain.
* Update Company now accepts `external_id` (`string | integer | null`) with the same semantics as `domain`: trimmed, but case is **preserved** (byte-exact — `ACCT_1` and `acct_1` are different ids), 1 to 190 characters, integers stored as their decimal string, and a blank string treated as `null`.
* Setting an `external_id` that already belongs to another company in the Space is rejected with `409` — `{ message, field, conflicting_company_id }` — and nothing is written. `field` can now be `domain` or `external_id`.
* Sending `external_id: null` releases the company's claim on the identifier; the company keeps its `id`, history, and contacts.
* The "at least one field" validation message on Update Company is now "At least one of domain, external\_id or name must be provided."
* `external_id` is only honored by event ingestion when the Space's company identity mode is **External ID**. In the default **Auto** mode, the value is stored and returned through this API but ignored for grouping.

**New endpoints: Attach / Detach Contact Company** — [`PUT /contacts/{id}/company`](https://docs.cometly.com/api-reference/endpoint/attach-contact-company) and [`DELETE /contacts/{id}/company`](https://docs.cometly.com/api-reference/endpoint/detach-contact-company) let you move a contact onto a different company, or off its company entirely, without waiting for another event.

* A contact belongs to at most one company per Space — attaching moves it off any company it currently belongs to.
* The contact's conversions, touchpoints, and visit metadata are re-stamped with the new (or `null`) company id in the same transaction, so company-level reports and the [Companies dataset](https://docs.cometly.com/data-warehouse/datasets/companies.md) in the data warehouse follow immediately.
* Both calls are idempotent: repeating an attach with the contact's current company id, or detaching an already-company-less contact, re-stamps rows (or no-ops) with a `200` rather than an error.
* Rate limited at **60 requests per minute** per Space, the same bucket as [Update Contact](https://docs.cometly.com/api-reference/endpoint/update-contact.md).
* What happens next depends on the Space's company identity mode: in **Auto** mode, the tracker only assigns a company to a contact that currently has none, so a manual attach sticks and a manual detach is undone by the contact's next business-email event; in **External ID** mode, the next event carrying a different `company_external_id` re-points the contact again either way.
* There is no MCP tool for these endpoints yet.

**Webhook mapping destinations** — `Company External ID` and `Company Name` are now available as mapping destination fields on every webhook integration, alongside your existing field mappings. They map to the same `company_external_id` and `company_name` keys as [Create Event](https://docs.cometly.com/api-reference/endpoint/create-event.md).

**Company Tracking settings** — a new **Space Settings → Additional Setup → Company Tracking** page holds the company identity mode (**Auto**, the default, groups companies by business-email domain; **External ID** groups them by `company_external_id` alone) alongside the ad-platform conversion identity mode. `company_external_id` sent on events is only honored in External ID mode.

**New guide: Account-level attribution for B2B** — [Account-level attribution for B2B (company external ID)](https://docs.cometly.com/guides/b2b-account-attribution.md) walks through using `company_external_id` to attribute a conversion by one teammate to an ad another teammate clicked, including webhook/Stripe metadata mapping and the ad-platform conversion identity setting.

***

## v1.2.0

### September 3, 2026

**Email lookup for List Contacts** — [`GET /contacts`](https://docs.cometly.com/api-reference/endpoint/list-contacts) now accepts an `email` query parameter to look contacts up by exact address instead of, or in addition to, a creation-date range. Accepts a single address, a comma-separated list, or a repeated `email[]` parameter — up to **100** addresses per request.

* Matching is exact (not partial or fuzzy) and case-insensitive, with surrounding whitespace trimmed. It resolves against the contact's primary email, all secondary emails, and emails captured on profiles that were later merged into the contact, so an address that only ever appeared on a merged-away profile still finds the surviving contact.
* `start_date` / `end_date` are now optional when `email` is supplied, but remain required as a pair otherwise — sending only one is a `422` regardless of `email`.
* `email` and a date range can be combined; both conditions AND together.
* No match returns a normal `200` with an empty `data` array, never a `404`, and several distinct contacts can legitimately share an address — all of them are returned.
* The rate limit is unchanged at **15 requests per minute** per Space, which is why the batch form exists: batch up to 100 addresses into a single call rather than one call per address for bulk reconciliation.
* The [`list_contacts`](https://docs.cometly.com/mcp/tools/list-contacts) MCP tool supports the same `email` parameter (as an array only — no comma-separated string form).

**New endpoint: Get Contact by Email** — [`GET /contacts/by-email/{email}`](https://docs.cometly.com/api-reference/endpoint/get-contact-by-email) and `GET /contacts/by-email?email=` look up a single contact by address, for when you expect exactly one match. The response is identical to [Get Contact](https://docs.cometly.com/api-reference/endpoint/get-contact.md), including all of its optional query parameters (`include_comet_tokens`, `include_events`, `hide_direct_touchpoints`, `use_custom_field_labels`, `include_browsing_session_data`).

* Resolution uses the same rules as the `email` filter above: exact, case-insensitive, whitespace-trimmed, spanning the contact's primary email, secondary emails, and emails from merged-away profiles.
* Returns `404` when no contact matches, and `409` with `contact_ids` when more than one contact matches — mirroring the `409` on [Delete Contact PII](https://docs.cometly.com/api-reference/endpoint/delete-contact-pii.md). Use the List Contacts `email` filter to see all matches, or request one of the returned `contact_ids` via `GET /contacts/{id}`.
* Rate limited at **30 requests per minute** per Space — the same bucket as [Get Contact](https://docs.cometly.com/api-reference/endpoint/get-contact.md), not the 15/minute limit on List Contacts.

***

## MCP v2.3.0

### September 2, 2026

**Personal access tokens (PATs) are now available for server-side and headless MCP agents.** If you're running a CI job, backend service, or any script without a browser, you no longer need to work around the OAuth flow. Generate a token directly from **Settings → Integrations → MCP** under **MCP Access Tokens**, name it, and send it as `Authorization: Bearer` like any other MCP token.

Key details:

* A personal access token behaves exactly like an OAuth-issued token: tied to your user account, working for a single Space, with your Space access re-checked on every request.
* Tokens don't expire. Revoke them when the agent is decommissioned.
* You can generate tokens until you hold up to **25 MCP tokens for a Space**; tokens issued to OAuth clients count toward that number.
* All MCP tokens, OAuth- and PAT-issued alike, are listed and revocable from the same **Settings → Integrations → MCP** page.

See [Authentication](https://docs.cometly.com/mcp/authentication.md#server-side-agents-pat) for the full flow and a `.mcp.json` config example.

***

## v1.1.1

### September 2, 2026

**Company identity rebuild** — a company's stable identity is now its numeric `id`, matched via lookup tables keyed on an email `domain` and/or a customer-supplied external ID (each unique per Space). This changes `domain` semantics across the Companies endpoints:

* **`domain` is now nullable** on [Get Company](https://docs.cometly.com/api-reference/endpoint/get-company.md) and [List Companies](https://docs.cometly.com/api-reference/endpoint/list-companies.md). It's `null` for a company identified only by an external ID, with no associated email domain.
* **[Update Company](https://docs.cometly.com/api-reference/endpoint/update-company.md)**: `domain` is an identifier, not just a label — changing it moves the company's claim on that domain. Values are trimmed and lowercased before storing (a blank string is treated as `null`), matching ingestion. Sending `domain: null` releases the company's claim on its domain: the company keeps its `id`, history, and contacts, but future events from that domain will create or match a different company. If the new domain already belongs to another company in the Space, the request is now rejected with **`409 Conflict`** — `{ message, field: "domain", conflicting_company_id }` — and nothing is changed.
* **`name: null` is now rejected.** The tracker's `name` column is required, so sending `name: null` on Update Company now returns `422` ("The name must be a string and cannot be null.") instead of clearing the value. Omit the key to leave `name` untouched.
* **Companies dataset** (Data Warehouse): `domain` is no longer a locked column — it's optional and nullable, matching the API. A new optional `external_id` column is available (the customer's own company identifier). `id` and `created_at` remain locked.

`external_id` is not yet exposed on the Companies API responses — that's tracked separately.

***

## v1.1.0

### August 7, 2026

**Delete Contact PII endpoint** — Added [`DELETE /contacts/{id}/pii`](https://docs.cometly.com/api-reference/endpoint/delete-contact-pii) and `DELETE /contacts/pii?email={email}` for permanently scrubbing a contact's personally identifiable information. Exactly one of `id` or `email` must be provided. The request validates and resolves the target contact synchronously, then queues the scrub and returns `202 Accepted` with `{ contact_id, status: "queued", message }` — call [Get Contact](https://docs.cometly.com/api-reference/endpoint/get-contact.md) afterward to confirm the fields have cleared.

* **Deleted**: all emails, phones, names, locations, devices, IPs, tracking IDs, and comet tokens for the contact (including data inherited from merged profiles), all raw browsing-session hits, and the contact's own `name`, `email`, `phone`, `location`, `city`, `state`, `country`, `device_type`, `os`, `browser`, `language`, and all 30 custom fields.
* **Kept**: the contact record (`id`, `created_at`), its events and journey, and its merge history. Event metadata (webhook payloads, URL query strings) can still contain PII — delete individual events via [Delete Event](https://docs.cometly.com/api-reference/endpoint/delete-event.md) if needed.
* Returns `404` if the `id` or `email` doesn't resolve to a contact in your space, and `409` with `contact_ids` if `email` matches more than one distinct contact — nothing is deleted in that case. Unlike [Delete Event](https://docs.cometly.com/api-reference/endpoint/delete-event.md), this endpoint is **not** idempotent on missing targets.

***

## MCP v2.2.0

### June 18, 2026

**OAuth Client ID Metadata Documents (CIMD) are now supported and are the preferred registration path for new custom MCP clients.** Instead of calling the registration endpoint, you host a JSON metadata document at a stable `https://` URL and use that URL as your `client_id` — no Dynamic Client Registration call required. Cometly fetches, validates, and caches the document on the first `/authorize` request.

Key details:

* The document must include `client_id` (equal to its own URL), `client_name`, `redirect_uris`, and `token_endpoint_auth_method: "none"`.
* Redirect URIs must be loopback or same-origin https (same scheme, host, and port as the `client_id` URL). Cross-origin https and custom URI schemes are not accepted for CIMD clients — use DCR for custom schemes.
* The document is cached up to 24 hours (respecting `Cache-Control: max-age`; default window 15 minutes).
* Support is advertised as `client_id_metadata_document_supported: true` in the authorization server metadata. DCR remains available as a fallback.

See [Authentication](https://docs.cometly.com/mcp/authentication.md#client-id-metadata-document-cimd) for the full specification and a document example.

***

## MCP v2.1.2

### June 10, 2026

**Major hosted MCP clients now complete OAuth Dynamic Client Registration out of the box, with no operator configuration required.** Claude (claude.ai), ChatGPT, Cursor, VS Code for the Web, Grok, Gemini, and Perplexity are all accepted by default. See [Authentication](https://docs.cometly.com/mcp/authentication.md#default-allowed-https-hosts) for the full host list.

***

## MCP v2.1.1

### June 3, 2026

**Dynamic Client Registration now accepts a partial `redirect_uris` array.** Previously, if any single URI in the `redirect_uris` array failed the redirect URI policy, the entire registration was rejected with `400 invalid_redirect_uri`. Now the endpoint registers only the valid subset and drops the rest — a `201` response's `redirect_uris` field reflects the accepted URIs, which may be fewer than you submitted. The registration is only rejected outright when **none** of the supplied URIs are valid. The per-URI validation rules (loopback, allowlisted https host, approved custom scheme, reverse-DNS scheme) are unchanged. See [Authentication](https://docs.cometly.com/mcp/authentication.md) for the full policy table.

***

## v1.0.8

### May 26, 2026

Bug fixes and behavioral improvements for `custom_field_filters` on [List Contacts](https://docs.cometly.com/api-reference/endpoint/list-contacts.md) and [List Events](https://docs.cometly.com/api-reference/endpoint/list-events.md):

* **Age operators on date fields now work.** `age_greater_than`, `age_equal_to`, and `age_less_than` were documented but incorrectly rejected with a 422 when passed a whole-number day count. The validator now accepts numeric values for these operators on date fields (`profile_field_26`–`profile_field_30`).
* **Date filter comparisons are timezone-aware.** `equal_to`, `greater_than`, `less_than`, and `between` on date fields now evaluate against your space's configured timezone. `equal_to` expands to a full midnight-to-midnight range for the given day; `greater_than` compares against end-of-day. Previously these operators compared raw strings, which would miss column values with a stored time component.
* **Numeric `any` / `unknown` semantics.** For numeric fields, `any` matches contacts where the value is greater than `0`; `unknown` matches contacts where the value is `0` or unset.
* **`not_equal_to` and `not_contains` no longer include unset values.** Previously these operators could return contacts where the field was NULL or empty. If you need those contacts, add a separate `unknown` condition ANDed alongside.
* **Text filter literals.** The `_` and `\` characters in `contains`, `starts_with`, `ends_with`, and `contains_word` filter values are now treated as literal characters instead of LIKE wildcards.

***

## MCP v2.1.0

### May 21, 2026

**Removed** the four export tools — `request_event_export`, `request_contact_export`, `request_company_export`, and `get_export_status`. Bulk extraction is better handled by the [Public API V1 export endpoints](https://docs.cometly.com/api-reference/endpoint/create-event-export.md) (programmatic) or the in-app CSV export buttons (interactive). Routing the rows through an MCP turn just consumed tool slots and added a polling round-trip without giving the agent any analytical leverage. Use [`query_events_aggregated`](https://docs.cometly.com/mcp/tools/query-events-aggregated), [`query_contacts_aggregated`](https://docs.cometly.com/mcp/tools/query-contacts-aggregated), or the various `query_ad_metrics_*` tools when the agent needs to *reason* about large datasets — not export them.

The MCP catalog is now **50 external tools across 14 toolsets** (down from 54 / 15).

***

## MCP v2.0.0

### May 15, 2026

Major expansion of the Cometly MCP server — from **7 read-only tools to 54 external tools** across 15 toolsets, plus the first MCP **Resources** and **Prompts**. Backwards compatible: every v1 tool kept its original input/output shape, with `format: "csv" | "json" | "yaml"` added as an opt-in.

**New toolsets** (49 new tools):

* **Workspace orientation** — [`get_workspace_context`](https://docs.cometly.com/mcp/tools/get-workspace-context), [`list_custom_events`](https://docs.cometly.com/mcp/tools/list-custom-events), [`list_my_spaces`](https://docs.cometly.com/mcp/tools/list-my-spaces), [`list_metric_catalog`](https://docs.cometly.com/mcp/tools/list-metric-catalog), [`list_filterable_fields`](https://docs.cometly.com/mcp/tools/list-filterable-fields), [`list_user_defined_metrics`](https://docs.cometly.com/mcp/tools/list-user-defined-metrics), [`resolve_date_range`](https://docs.cometly.com/mcp/tools/resolve-date-range).
* **Search** — [`search_workspace`](https://docs.cometly.com/mcp/tools/search-workspace).
* **Analytics depth** — [`query_ad_metrics_compare`](https://docs.cometly.com/mcp/tools/query-ad-metrics-compare), [`query_attribution_models`](https://docs.cometly.com/mcp/tools/query-attribution-models), [`query_metric_breakdown`](https://docs.cometly.com/mcp/tools/query-metric-breakdown).
* **Event aggregations** — [`query_events_aggregated`](https://docs.cometly.com/mcp/tools/query-events-aggregated), [`list_event_types`](https://docs.cometly.com/mcp/tools/list-event-types).
* **Journeys** — [`get_contact_journey`](https://docs.cometly.com/mcp/tools/get-contact-journey), [`query_contacts_aggregated`](https://docs.cometly.com/mcp/tools/query-contacts-aggregated), [`get_company_journey`](https://docs.cometly.com/mcp/tools/get-company-journey).
* **Ads Manager hierarchy** — [`list_ad_accounts`](https://docs.cometly.com/mcp/tools/list-ad-accounts), [`list_campaigns`](https://docs.cometly.com/mcp/tools/list-campaigns), [`list_adsets`](https://docs.cometly.com/mcp/tools/list-adsets), [`list_ads`](https://docs.cometly.com/mcp/tools/list-ads), [`get_ad_entity`](https://docs.cometly.com/mcp/tools/get-ad-entity).
* **Reports & dashboards** — [`list_dashboards`](https://docs.cometly.com/mcp/tools/list-dashboards), [`get_dashboard`](https://docs.cometly.com/mcp/tools/get-dashboard), [`list_reports`](https://docs.cometly.com/mcp/tools/list-reports), [`get_report_definition`](https://docs.cometly.com/mcp/tools/get-report-definition), [`run_saved_report`](https://docs.cometly.com/mcp/tools/run-saved-report), [`analyze_report`](https://docs.cometly.com/mcp/tools/analyze-report), [`list_subscriptions`](https://docs.cometly.com/mcp/tools/list-subscriptions), [`get_subscription_last_run`](https://docs.cometly.com/mcp/tools/get-subscription-last-run).
* **Segments** — `list_segments`, `get_segment`, `query_segment_membership`.
* **Integrations** — [`list_integrations`](https://docs.cometly.com/mcp/tools/list-integrations), [`get_pixel_status`](https://docs.cometly.com/mcp/tools/get-pixel-status), [`list_event_mappings`](https://docs.cometly.com/mcp/tools/list-event-mappings).
* **Health & diagnostics** — [`get_space_health`](https://docs.cometly.com/mcp/tools/get-space-health), [`debug_data_flow`](https://docs.cometly.com/mcp/tools/debug-data-flow), plus the existing `inspect_site` / `verify_pixel_events`.
* **Webhook debugging** — [`list_recent_webhooks`](https://docs.cometly.com/mcp/tools/list-recent-webhooks), [`get_webhook_event`](https://docs.cometly.com/mcp/tools/get-webhook-event) (payloads PII-redacted; prompt-injection patterns flagged in a warning footer).
* **Exports** — `request_event_export`, `request_contact_export`, `request_company_export`, `get_export_status`. (Removed in v2.1.0.)
* **AI helpers** — [`search_cometly_docs`](https://docs.cometly.com/mcp/tools/search-cometly-docs), [`get_chart_spec_template`](https://docs.cometly.com/mcp/tools/get-chart-spec-template).

**Resources** (read-only, subscribable):

* `cometly://workspace/context`
* `cometly://catalog/metrics`
* `cometly://catalog/attribution-models`
* `cometly://catalog/dimensions`
* `cometly://catalog/custom-events`

**Prompts** (slash-command templates):

* `analyze_performance`
* `compare_attribution_models`
* `weekly_review`
* `find_underperformers`

**Cross-cutting improvements:**

* **Custom event label resolution** — analytics tools accept either `custom_event_2` or the configured label ("Deal Created") in their inputs. Output rewrites slot ids to labels with a `# label_map:` footer for round-tripping.
* **Empty-state hints** — analytics tools annotate suspicious all-zero results with hints like "No facebook\_ads account is connected to this space" or "Last google\_ads sync was 3 days ago".
* **Token-budget pagination** — responses cap around \~6,000 tokens with a `truncated_at_token_budget: true` footer + opaque `next_cursor`.
* **CSV default for new tools** — \~50% fewer tokens than JSON for tabular results. Legacy v1 tools keep JSON as default.
* **DST caveat** — `query_ad_metrics` and `resolve_date_range` surface a DST advisory when the requested window crosses a transition.
* **Honest forecasting language** — softened "anomaly detection" / "forecast" claims in tool descriptions to "directional reads" — we don't run statistical models, the agent does threshold math.
* **`external: false` filtering** — tools that only make sense in-app (chat history, file attachments) are hidden from external MCP clients via a server-level `shouldRegister` filter.

***

## v1.0.7

### May 14, 2026

* **Update Contact endpoint** — Added [PUT /contacts/{id}](https://docs.cometly.com/api-reference/endpoint/update-contact.md) for updating an existing contact's `emails`, `phones`, `names`, `locations`, and `custom_fields`. Uses **sparse PUT** semantics: any field you include replaces the existing collection in full; any field you omit is left untouched. Empty arrays (`[]`) wipe a collection; providing `custom_fields` clears every key not in the object.
* **Update Company endpoint** — Added [PUT /companies/{id}](https://docs.cometly.com/api-reference/endpoint/update-company.md) for updating a company's `domain` and `name`. Uses sparse PUT semantics — only the fields you include are modified.
* **`name` field on Get Company** — The [Get Company](https://docs.cometly.com/api-reference/endpoint/get-company.md) response now includes `name` alongside `id` and `domain`. This is an additive change; existing fields are unchanged.
* **`custom_field_filters` parameter on List Contacts** — Added `custom_field_filters` to the [List Contacts](https://docs.cometly.com/api-reference/endpoint/list-contacts.md) endpoint. Accepts an array of AND-joined conditions (max 10) for filtering contacts by their custom profile field values. Each condition takes `{ field, operator, value }` (or `{ field, operator, start, end }` for the `between` operator). The `field` must reference a `profile_field_N` slot configured with a label in your space; operator vocabulary depends on the field's type (text / number / date).
* **`custom_field_filters` parameter on List Events** — Same parameter added to the [List Events](https://docs.cometly.com/api-reference/endpoint/list-events.md) endpoint, narrowing results to events whose owning contact matches the conditions. Same shape and operator vocabulary as List Contacts.

***

## v1.0.6

### April 20, 2026

* **`include_browsing_session_data` parameter on Get Contact** — Added `include_browsing_session_data` to the [Get Contact](https://docs.cometly.com/api-reference/endpoint/get-contact.md) endpoint. When set to `1`, the response includes a `browsing_session_hits` array with up to the last 1000 raw browsing hits (page views) for the contact, ordered by most recent first. Each hit includes `event_url` (full URL), `referrer_host`, `source`, `country`, `device_type`, `browser`, `os`, `event_name`, and `event_time_utc`.

***

## v1.0.5

### April 7, 2026

* **`include_events` parameter on Get Contact** — Added `include_events` to the [Get Contact](https://docs.cometly.com/api-reference/endpoint/get-contact.md) endpoint. When set to `1`, the response includes an `events` array containing the contact's full journey — all conversions and touchpoints sorted by most recent first. Conversion events include `event_name`, `amount`, `event_url`, `order_id`, `order_name`, `channel` (browser/server), and `integration`. Touchpoint events include `source`, `touchpoint_url`, `referrer_url`, and the full ad hierarchy (`ad_name`, `adset_name`, `campaign_name`, `account_name`).
* **`hide_direct_touchpoints` parameter on Get Contact** — Added `hide_direct_touchpoints` (default `1`) to the [Get Contact](https://docs.cometly.com/api-reference/endpoint/get-contact.md) endpoint. When `include_events=1`, direct touchpoints are excluded by default. Set to `0` to include them.

***

## v1.0.4

### March 19, 2026

* **`use_custom_field_labels` parameter** — Added `use_custom_field_labels` to the [List Contacts](https://docs.cometly.com/api-reference/endpoint/list-contacts.md) and [Get Contact](https://docs.cometly.com/api-reference/endpoint/get-contact.md) endpoints. When set to `1`, custom field keys use user-defined labels (e.g. `"Customer Age"`) instead of raw column names (e.g. `"profile_field_1"`). Fields without a configured label retain their raw column name.

***

## v1.0.3

### February 27, 2026

* **Ad hierarchy fields on List Events** — Added `ad_name`, `adset_id`, `adset_name`, `campaign_id`, `campaign_name`, `account_id`, and `account_name` as requestable fields on the [List Events](https://docs.cometly.com/api-reference/endpoint/list-events.md) endpoint. These fields require `sources` to be provided and return the ad, ad set, campaign, and account data from the attributed touchpoint.

***

## v1.0.2

### February 19, 2026

* **`include_all_emails` parameter** — Added `include_all_emails` to the [List Contacts](https://docs.cometly.com/api-reference/endpoint/list-contacts.md) and [Create Contact Export](https://docs.cometly.com/api-reference/endpoint/create-contact-export.md) endpoints. When set to `1`, returns all email addresses associated with a contact, including emails from merged profiles.

***

## v1.0.1

### February 17, 2026

* **Custom fields on Create Event** — The [Create Event](https://docs.cometly.com/api-reference/endpoint/create-event.md) endpoint now accepts custom profile fields (`profile_field_1` through `profile_field_30`) as root-level properties. Fields 1-15 accept text, 16-25 accept numbers (string or number), 26-30 accept dates.
* **`event_url` field** — Added `event_url` as a requestable field on the [List Events](https://docs.cometly.com/api-reference/endpoint/list-events.md) and [Create Event Export](https://docs.cometly.com/api-reference/endpoint/create-event-export.md) endpoints. Returns the full URL where the event occurred.

***

## v1.0.0

### Initial release


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.