# Cometly API Docs

- [Cometly API Documentation](https://docs.cometly.com/index.md): Welcome to the Cometly API documentation. Learn how to integrate and use our API to track conversions and manage your marketing data.
- [Authentication](https://docs.cometly.com/introduction/authentication.md): Learn how to authenticate your requests to the Cometly API
- [Rate Limiting](https://docs.cometly.com/introduction/rate-limiting.md): Understand API rate limits and how to handle them in your application
- [Status Codes](https://docs.cometly.com/introduction/status-codes.md): HTTP status codes and error handling in the Cometly API
- [Changelog](https://docs.cometly.com/changelog.md): Track changes, new features, and improvements to the Cometly API.
- [Create Event](https://docs.cometly.com/api-reference/endpoint/create-event.md): Create a new event to track conversions and user interactions
- [List Events](https://docs.cometly.com/api-reference/endpoint/list-events.md): Retrieve a paginated list of events with optional attribution filtering
- [Get Event](https://docs.cometly.com/api-reference/endpoint/get-event.md): Retrieve details of a specific event by its ID
- [Delete Event](https://docs.cometly.com/api-reference/endpoint/delete-event.md): Delete a specific event by its ID
- [Create Event Export](https://docs.cometly.com/api-reference/endpoint/create-event-export.md): Create an asynchronous export job to generate a downloadable file of events
- [Get Event Export](https://docs.cometly.com/api-reference/endpoint/get-event-export.md): Check the status of an export job and retrieve the download URL when ready
- [Create Contact](https://docs.cometly.com/api-reference/endpoint/create-contact.md): Create a new contact with arrays of emails, phones, names, and locations
- [List Contacts](https://docs.cometly.com/api-reference/endpoint/list-contacts.md): Retrieve a paginated list of contacts filtered by creation date or by email address
- [Get Contact](https://docs.cometly.com/api-reference/endpoint/get-contact.md): Retrieve details of a specific contact by its ID
- [Get Contact by Email](https://docs.cometly.com/api-reference/endpoint/get-contact-by-email.md): Retrieve a single contact by its email address
- [Update Contact](https://docs.cometly.com/api-reference/endpoint/update-contact.md): Update an existing contact's emails, phones, names, locations, or custom fields
- [Attach Contact Company](https://docs.cometly.com/api-reference/endpoint/attach-contact-company.md): Attach a contact to a company, moving it off any company it currently belongs to
- [Detach Contact Company](https://docs.cometly.com/api-reference/endpoint/detach-contact-company.md): Detach a contact from its current company
- [Delete Contact PII](https://docs.cometly.com/api-reference/endpoint/delete-contact-pii.md): Permanently scrub a contact's personally identifiable information, by contact ID or by email
- [Create Contact Export](https://docs.cometly.com/api-reference/endpoint/create-contact-export.md): Create an asynchronous export job to generate a downloadable file of contacts
- [Get Contact Export](https://docs.cometly.com/api-reference/endpoint/get-contact-export.md): Check the status of a contact export job and retrieve the download URL when ready
- [List Companies](https://docs.cometly.com/api-reference/endpoint/list-companies.md): Retrieve a paginated list of companies with optional date filtering
- [Get Company](https://docs.cometly.com/api-reference/endpoint/get-company.md): Retrieve details of a specific company by its ID
- [Update Company](https://docs.cometly.com/api-reference/endpoint/update-company.md): Update an existing company's domain, external ID, or name
- [Create Company Export](https://docs.cometly.com/api-reference/endpoint/create-company-export.md): Create an asynchronous export job to generate a downloadable file of companies
- [Get Company Export](https://docs.cometly.com/api-reference/endpoint/get-company-export.md): Check the status of a company export job and retrieve the download URL when ready
- [MCP Overview](https://docs.cometly.com/mcp/overview.md): Connect Claude Desktop, Cursor, and any MCP-aware client to your Cometly workspace and let it query your marketing analytics in natural language.
- [Authentication](https://docs.cometly.com/mcp/authentication.md): OAuth 2.1 with PKCE for browser-based clients (CIMD or Dynamic Client Registration), or a personal access token for server-side agents. MCP-aware clients like Claude Desktop and Cursor handle OAuth automatically.
- [Rate Limits & Errors](https://docs.cometly.com/mcp/rate-limits-and-errors.md): Per-Space rate limits on the Cometly MCP endpoint, the structured `[error_class]` envelope, and how connected AI clients recover from failures.
- [Cursor](https://docs.cometly.com/mcp/connecting/cursor.md): Add the Cometly MCP server to Cursor and ask questions about your marketing data right from the chat sidebar.
- [Claude Desktop](https://docs.cometly.com/mcp/connecting/claude-desktop.md): Install the Cometly MCP server in Claude Desktop and ask Claude about your marketing data in plain English.
- [Claude Code](https://docs.cometly.com/mcp/connecting/claude-code.md): Use the Cometly MCP server from Claude Code (Anthropic's CLI) so your terminal agent can pull live marketing data.
- [ChatGPT](https://docs.cometly.com/mcp/connecting/chatgpt.md): Connect the Cometly MCP server to ChatGPT's Desktop app (and any other MCP-aware OpenAI client) so you can ask GPT-5 about your marketing data.
- [Tools Overview](https://docs.cometly.com/mcp/tools/overview.md): Every MCP tool Cometly exposes, organized by toolset, with when-to-use guidance.
- [get_workspace_context](https://docs.cometly.com/mcp/tools/get-workspace-context.md): One cheap call that returns space orientation data — timezone, currency, connected ad accounts, custom event label map, and default attribution.
- [list_custom_events](https://docs.cometly.com/mcp/tools/list-custom-events.md): List this space's configured custom conversion event slots with their human labels.
- [list_my_spaces](https://docs.cometly.com/mcp/tools/list-my-spaces.md): Every space the authenticated user can access, with a marker on the one bound to this MCP session.
- [list_metric_catalog](https://docs.cometly.com/mcp/tools/list-metric-catalog.md): Every analytics metric slug supported by query_ad_metrics et al, scoped to what this space actually uses.
- [list_filterable_fields](https://docs.cometly.com/mcp/tools/list-filterable-fields.md): Every field that can appear inside a filters object — slug, type, allowed operators, and labels for profile fields.
- [list_user_defined_metrics](https://docs.cometly.com/mcp/tools/list-user-defined-metrics.md): User-defined custom metric formulas configured in the report builder.
- [resolve_date_range](https://docs.cometly.com/mcp/tools/resolve-date-range.md): Turn a natural-language or preset date phrase into concrete start/end UTC bounds in the space's timezone.
- [search_workspace](https://docs.cometly.com/mcp/tools/search-workspace.md): Fuzzy search across campaigns, ad sets, ads, contacts, companies, reports, and dashboards.
- [query_ad_metrics](https://docs.cometly.com/mcp/tools/query-ad-metrics.md): Aggregated ad performance metrics from the Cometly report builder — ROAS, CPA, spend, conversions, with grouping, attribution, and filters.
- [query_ad_metrics_compare](https://docs.cometly.com/mcp/tools/query-ad-metrics-compare.md): Run the same metrics across two periods (current vs previous) in one call with side-by-side deltas.
- [query_attribution_models](https://docs.cometly.com/mcp/tools/query-attribution-models.md): Run the same metrics query across multiple attribution models in one call.
- [query_metric_breakdown](https://docs.cometly.com/mcp/tools/query-metric-breakdown.md): Top-N ranked drill-down across one or more dimensions.
- [list_events](https://docs.cometly.com/mcp/tools/list-events.md): List individual conversion events with optional attribution, field selection, and custom-field-value filtering.
- [get_event](https://docs.cometly.com/mcp/tools/get-event.md): Retrieve full detail for a single conversion event by ID.
- [query_events_aggregated](https://docs.cometly.com/mcp/tools/query-events-aggregated.md): Aggregated count / sum / group-by over conversion events, without hydrating individual event rows.
- [list_event_types](https://docs.cometly.com/mcp/tools/list-event-types.md): Distinct event names in this space with first/last seen dates and a count over a lookback window.
- [list_contacts](https://docs.cometly.com/mcp/tools/list-contacts.md): List contacts (profiles) created within a date range, or look them up by exact email address, with optional custom-field include and value filtering.
- [get_contact](https://docs.cometly.com/mcp/tools/get-contact.md): Retrieve full detail for a single contact (profile) by ID, including journey, browsing data, and tracking tokens.
- [get_contact_journey](https://docs.cometly.com/mcp/tools/get-contact-journey.md): Full chronological timeline for a single contact — touchpoints interleaved with conversions.
- [query_contacts_aggregated](https://docs.cometly.com/mcp/tools/query-contacts-aggregated.md): Aggregated count / group-by over contacts (people), pinned to profile-mode aggregation.
- [list_companies](https://docs.cometly.com/mcp/tools/list-companies.md): List companies tracked in your Space. Returns one row per company with id, domain, and external_id.
- [get_company](https://docs.cometly.com/mcp/tools/get-company.md): Retrieve detail for a single company by ID.
- [get_company_journey](https://docs.cometly.com/mcp/tools/get-company-journey.md): Full chronological timeline for a single company — touchpoints + conversions across all contacts.
- [list_ad_accounts](https://docs.cometly.com/mcp/tools/list-ad-accounts.md): Every connected ad account across all platforms with currency, status, and last sync timestamp.
- [list_campaigns](https://docs.cometly.com/mcp/tools/list-campaigns.md): Campaigns across connected ad platforms with status, objective, and budget snapshot.
- [list_adsets](https://docs.cometly.com/mcp/tools/list-adsets.md): Ad sets / ad groups across connected ad platforms with status and budget.
- [list_ads](https://docs.cometly.com/mcp/tools/list-ads.md): Individual ads / creatives across connected ad platforms.
- [get_ad_entity](https://docs.cometly.com/mcp/tools/get-ad-entity.md): Full detail for a single campaign, adset, or ad — creative, targeting, delivery, budget.
- [list_dashboards](https://docs.cometly.com/mcp/tools/list-dashboards.md): Every dashboard (custom report grid) in this space.
- [get_dashboard](https://docs.cometly.com/mcp/tools/get-dashboard.md): Layout and contained reports for one dashboard.
- [list_reports](https://docs.cometly.com/mcp/tools/list-reports.md): Saved reports across this space, optionally filtered to one dashboard.
- [get_report_definition](https://docs.cometly.com/mcp/tools/get-report-definition.md): Full saved-report config — metrics, filters, attribution, group_by, sources, options.
- [run_saved_report](https://docs.cometly.com/mcp/tools/run-saved-report.md): Execute a saved report as configured and return the dataset the dashboard renders.
- [analyze_report](https://docs.cometly.com/mcp/tools/analyze-report.md): Runs Cometly's tuned report-analysis pipeline against a saved report and returns the AI-generated markdown summary.
- [list_subscriptions](https://docs.cometly.com/mcp/tools/list-subscriptions.md): Scheduled report digest subscriptions for this space.
- [get_subscription_last_run](https://docs.cometly.com/mcp/tools/get-subscription-last-run.md): Most recent dispatched digest for a subscription.
- [list_segments](https://docs.cometly.com/mcp/tools/list-segments.md): Contact segments defined in this space.
- [get_segment](https://docs.cometly.com/mcp/tools/get-segment.md): Single segment's definition (conditions, last refresh, size).
- [query_segment_membership](https://docs.cometly.com/mcp/tools/query-segment-membership.md): Paginated members (contacts) of a segment.
- [list_integrations](https://docs.cometly.com/mcp/tools/list-integrations.md): Every connected integration in this space — OAuth (HubSpot, Shopify, Slack, ...) and inbound webhooks.
- [get_pixel_status](https://docs.cometly.com/mcp/tools/get-pixel-status.md): Per-domain pixel + CAPI + form-tracking installation health.
- [list_event_mappings](https://docs.cometly.com/mcp/tools/list-event-mappings.md): How external events from each integration map to Cometly events.
- [get_space_health](https://docs.cometly.com/mcp/tools/get-space-health.md): Composite tracking-health diagnostic — pixel, UTM coverage, form tracking, ad cache sync, CAPI readiness.
- [debug_data_flow](https://docs.cometly.com/mcp/tools/debug-data-flow.md): Trace why a specific event isn't appearing — composes conversion counts + recent webhook activity + integration freshness.
- [inspect_site](https://docs.cometly.com/mcp/tools/inspect-site.md): Server-side fetch + static analysis of a customer page — pixel installation, scripts, forms, iframes.
- [verify_pixel_events](https://docs.cometly.com/mcp/tools/verify-pixel-events.md): Confirm pixel events are actually arriving from a domain by querying Cometly's ingestion logs.
- [list_recent_webhooks](https://docs.cometly.com/mcp/tools/list-recent-webhooks.md): Recent webhook receipts with status, source, and summarized payload — payloads are PII-summarized, not raw.
- [get_webhook_event](https://docs.cometly.com/mcp/tools/get-webhook-event.md): Full diagnostic for one webhook fire — redacted payload, parse result, error trace.
- [search_cometly_docs](https://docs.cometly.com/mcp/tools/search-cometly-docs.md): Lightweight substring search across Cometly's product documentation.
- [get_chart_spec_template](https://docs.cometly.com/mcp/tools/get-chart-spec-template.md): Chart.js v4 templates the agent populates with values from query_ad_metrics.
- [Resources Overview](https://docs.cometly.com/mcp/resources/overview.md): Subscribable read-only data the MCP server exposes alongside tools — workspace context, metric catalogs, dimension lists.
- [Prompts Overview](https://docs.cometly.com/mcp/prompts/overview.md): Reusable prompt templates clients surface as slash-commands — pre-filled multi-step analyses.
- [Sending Data to Cometly](https://docs.cometly.com/concepts/sending-data-to-cometly.md): Learn the two ways to send event data to Cometly: webhooks and the API
- [Comet Token](https://docs.cometly.com/concepts/comet-token.md): Learn how to use the cometToken() function to improve attribution accuracy when sending events via the API
- [Exports vs Pagination](https://docs.cometly.com/concepts/exports-vs-pagination.md): Learn when to use async exports versus paginated list endpoints for retrieving large datasets
- [Account-level attribution for B2B (company external ID)](https://docs.cometly.com/guides/b2b-account-attribution.md): Attribute ad-platform conversions to the account that clicked the ad, not just the person who paid, using company_external_id.
- [Data Warehouse Exports](https://docs.cometly.com/data-warehouse/overview.md): Export your raw Cometly data as Parquet files to your own S3 or GCS bucket for loading into a data warehouse or lake.
- [Set up an S3 destination](https://docs.cometly.com/data-warehouse/s3-destination.md): Create an AWS IAM user and S3 bucket so Cometly can write export files to your account.
- [Set up a Google Cloud Storage destination](https://docs.cometly.com/data-warehouse/gcs-destination.md): Create a GCS bucket, service account, and HMAC key so Cometly can write export files to your bucket.
- [Set up a Snowflake destination](https://docs.cometly.com/data-warehouse/snowflake-destination.md): Create a Snowflake role, service user, and access token so Cometly can load export data directly into your warehouse.
- [Set up a BigQuery destination](https://docs.cometly.com/data-warehouse/bigquery-destination.md): Grant Cometly's service account access to a BigQuery dataset you own so Cometly can load export data directly into a table.
- [Create an export](https://docs.cometly.com/data-warehouse/create-export.md): Configure a dataset, cadence, window, and columns, and load the data into one of your destinations.
- [Raw touchpoints](https://docs.cometly.com/data-warehouse/datasets/raw-touchpoints.md): Every tracked touchpoint as recorded, over the export window.
- [Raw conversions](https://docs.cometly.com/data-warehouse/datasets/raw-conversions.md): Every conversion as recorded — the unattributed counterpart to touchpoints.
- [Raw hits](https://docs.cometly.com/data-warehouse/datasets/raw-hits.md): Every tracked pixel hit as recorded, unfiltered across all event types.
- [Attributed conversions](https://docs.cometly.com/data-warehouse/datasets/attributed-conversions.md): Conversions joined to their attributed touchpoints, at the attributed-touchpoint grain.
- [Contacts](https://docs.cometly.com/data-warehouse/datasets/contacts.md): Every contact created in the export window, with its identity and custom fields.
- [Companies](https://docs.cometly.com/data-warehouse/datasets/companies.md): Every company created in the export window.
- [Ad analytics](https://docs.cometly.com/data-warehouse/datasets/ad-analytics.md): Daily ad-performance rows per channel — Facebook, Google, LinkedIn, TikTok, Microsoft, Reddit, Taboola, AdRoll, Whop, and X.

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)