Conversions API

Export published Conversion Performance reports for a website and an optional conversion path. Use the report to compare starting sessions, completed conversions, configured conversion values, observed routes and acquisition patterns across current and previous periods.

Create with POST https://app.wheremore.com/api/v2/exports/conversions . Retrieve with GET https://app.wheremore.com/api/v2/exports/{export_id} . This guide describes default data contract 2026-09-19 . See API Access and API Keys for authentication, shared responses and export handling.

Choose the website and path

Use the public workspace ID from API Access → Your Workspaces and Markets. Choose exactly one website selector: numeric domain_id  or domain , matching the accessible website label without regard to case. Prefer IDs for durable integrations.

To select a path, supply path_id  or path , not both. Path names must identify exactly one available path without regard to case. Omitting both gives the website-wide report. Available paths can include active configured paths and historical paths retained in reporting data.

This API has no conversion-path listing endpoint. Obtain the configured IDs or labels from your Wheremore configuration or workspace administrator. Names are resolved to numeric IDs before the export request is saved.

Request fields

audience  uses the recorded authenticated-user status; it does not prove that someone is a new or existing customer. device: "unknown"  is an explicit device bucket, different from including all devices.

With campaign_mode: "all" , the campaign filter is cleared. To request traffic whose campaign is recorded as empty, send "campaign_mode": "exact", "campaign": "" ; missing/unobserved acquisition data is not automatically equivalent to an observed empty campaign.

Unknown fields are rejected. The older include_journey  option is removed: available journey/route information is in the published detail panels.

Create and retrieve the report

Replace the sample IDs and dates. Set WHEREMORE_API_KEY  securely first.

curl --fail-with-body -X POST \
  "https://app.wheremore.com/api/v2/exports/conversions" \
  -H "X-API-Key: ${WHEREMORE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: conversion-report-20260919-001" \
  -d '{
    "workspace_id": "ws_your_workspace_id",
    "domain_id": 30,
    "path_id": 12,
    "date_from": "2026-09-01",
    "date_to": "2026-09-18",
    "device": "all",
    "audience": "all",
    "campaign_mode": "all",
    "data_contract": "2026-09-19"
  }'

1. Save export.id  from the response. HTTP 201 means ready and 202 means pending. POST is free and returns metadata only.
2. GET the saved ID:

curl --fail-with-body \
  "https://app.wheremore.com/api/v2/exports/exp_0123456789abcdef0123456789abcdef" \
  -H "X-API-Key: ${WHEREMORE_API_KEY}"

3. Pending GETs return 202 for free. A ready GET returns 200 with the report in data .

Retry an identical POST with the same idempotency key. Use a new one when changing the website, path, filters or dates, or requesting a later snapshot. Repeat GETs return the frozen report rather than recalculating it.

Returned data

This response fragment illustrates session measures only; a full period summary contains further fields:

{
  "current": {
    "starting_sessions": 100,
    "converting_sessions": 8,
    "session_conversion_rate": 8,
    "conversions": 10
  },
  "empty": false,
  "availability": "published"
}

Interpret the measures

A starting session belongs to the cohort anchored to its entry session. It is not a conversion record, attempt count or attribution credit. session_conversion_rate  is converting sessions divided by starting sessions, expressed as a percentage; unknown results remain null. Multiple completions can occur within a converting session, so conversions  need not equal converting_sessions .

conversion_value  contains configured conversion values, not verified revenue. Keep currencies and value types separate and preserve unknown-value indicators. Do not rename the result revenue  or sum unlike currencies into one monetary total.

Observed routes are partial tracking evidence, not complete customer histories. Open attempts are not failed journeys. Route panels distinguish completed journeys and confirmed dropoffs and retain availability/coverage information.

Entry acquisition and completion-based attribution answer different questions. Preserve their units, provisional states and coverage rather than treating them as interchangeable session counts.

Understand publication and history

export.status: "ready"  means a snapshot was saved. Inside data , status  can be ready , updating  or paused : the last publication can still be served while reporting updates or is paused. If the first publication is still building, the export remains pending.

The previous period is the preceding equivalent window. Before-history periods and unavailable comparisons retain null results; they are not measured zeros. history  describes the recorded rule-start boundary, not proof of uninterrupted capture. Keep its messages with charts and comparisons.

The API does not export an individual raw-session feed and does not expose the older sessions , total_sessions  or revenue  contract. Controls/options used inside Wheremore are not included in the report response.

Charges and limits

The first successful GET costs 0.5 credits if either returned period has starting sessions. Zero completed conversions does not make a report free when session data exists. A report with no starting sessions in either returned period has zero billable units. Check history flags before describing an empty result as measured inactivity.

Repeated GETs of the same paid export return identical data without another charge. New exports are separately billable. Exports expire seven days after creation and are subject to the 8 MiB saved-payload limit. There is no pagination for this report. The reporting reader also has capacity limits, so narrower dates or a single path may be needed before the saved-payload limit is reached.

Retrieval rechecks the owning user's workspace/domain access and the domain's workspace membership. Revoked access can block a saved report even after it was charged.

Troubleshooting

• 400 for website selection: supply exactly one of domain_id  or domain .
• Ambiguous or unavailable name: use a numeric ID. A website/path label must identify exactly one permitted selection.
• 400 for include_journey : remove the obsolete field and read detail_panels  instead.
• Blank comparison: inspect history.comparison_available , availability states and messages; do not replace nulls with zeros.
• Unexpected campaign result: verify campaign_mode  and exact campaign text. Empty recorded campaign and missing acquisition evidence differ.
• Report says updating or paused: it contains the last available publication. A new export can read a later publication once processing catches up.
• 503 on a large request: narrow dates or select one path. Persistent errors may indicate unavailable reporting dependencies; retain meta.request_id  for support.
• 403 on a previously readable report: check current workspace/domain permissions.

See API Access and API Keys for credit errors, retry behaviour, callbacks and retention, and Understanding Conversion Tracking for the underlying tracking concepts.