Retrieve reports data for project

Changed on

Fetch a report based on various parameters such as project, functions, quizzes, paywalls, and time ranges. This endpoint supports a variety of functions and filters for detailed analytical reporting. Available functions:

  • totalSubscriptionsAndRevenue: Returns total subscriptions, total revenue, charged revenue, LTV, and average subscription amount.
  • subscriptionsByDay: Provides subscriptions and revenue trends over time.
  • subscriptionsByPriceId: Groups subscriptions by price ID and provides revenue and LTV details.
  • subscriptionsByCountry: Groups subscriptions by country and shows total revenue.
  • subscriptionsByPlatform: Groups subscriptions by user platform (iOS, Android, Windows, Mac, Linux, Unknown) taken from user_visits.user_platform. Counts active, trialing, past_due and canceled subscriptions that have a paid invoice or a refund.
  • subscriptionsByLocation: Groups subscriptions by rounded user_visits.user_latitude/user_longitude (top 3000 points) with count and revenue, for map display.
  • stepAnswers: Answers given on one quiz funnel step (step_event_name, e.g. Step 03 goals) by the users who reached it: per answer key (screen block), the number of users per answer. A multi-choice answer is split so every option is counted once per user; free input is limited to the top 10 values. Answers come from user properties of the quizzes in which the step was reached.
  • visitsByLocation: Groups all non-bot user visits matching the filters by rounded user_visits.user_latitude/user_longitude (top 3000 points) with visit and user counts, for map display.
  • purchasesByWeekdayHour: Counts purchases (active/trialing subscriptions with real payment) and revenue by day of week (1 = Monday) and hour of creation in UTC, for heatmap display Each row also carries visit_count (visits by visit time) and visit_purchase_count (purchases attributed to the visit time) for the conversion mode.
  • subscriptionsByStatus: Breaks down subscriptions by status (e.g., active, incomplete, etc.).
  • dailyCompletionRate: Tracks completion and conversion rates by day.
  • quizFunnel: Provides detailed funnel step conversion rates for quizzes. Accepts answers_user_property / answers_user_property_value to count only the users who gave that answer (also for throughFunnel). Supports the optional group_by=user_country_code parameter to split the funnel by visitor country.
  • paywallConversionByDays: Tracks paywall conversion rates by day.
  • paywallFunnel: Shows the paywall funnel conversion breakdown.
  • subscribeToInstallRate: Tracks the rate of rhe percent of users who purchased subscription and installed the app after (meaning - requested subscription status using API).
  • utmReport: Funnel metrics grouped by UTM, country, or platform. Default grouping is campaign UTM (source_campaign_medium and related orders). Pass utm_grouping=country for a visitor-level country breakdown (user_country_code) or utm_grouping=user_platform for a visitor-level platform breakdown (user_platform). Both visitor groupings honor quizzes[] and the date range; rows are sorted by users_count descending. Visitor metrics (users_count, quizes_started, and earlier funnel steps) use quiz engagement. Subscription/revenue columns still attribute via subscription.quiz_id.
  • metaAdsSpendByDay: Meta (Facebook) Ads spend aggregated by day from the ads_reports ClickHouse table (populated by the Meta/Facebook sync pipeline only). Supported filters: project, from, to, utm_source[], utm_medium[], utm_campaign[], utm_content[], utm_term[]. Ignored filters: quizzes[], paywalls[], quizzesVersion[], paywallVersion[], payment_system, user_country_code, user_platform, experiment_id, experiment_variant, user_property, user_property_value, utm_grouping. Returns an array of daily rows with date, spend (USD when spend_usd is available), clicks, impressions, and purchases.
get/reports/getGraph

Request

  • Base URL
    https://api.web2wave.com/api
  • URL
    https://api.web2wave.com/api/reports/getGraph
  • Auth
    API key in header api_key

Query parameters

projectinteger required

The project ID for which the graph is being retrieved.

functions[]string[] required

A list of functions to be included in the graph. Example: totalSubscriptionsAndRevenue.

quizzes[]string[]

Optional list of quiz IDs for filtering.

paywalls[]string[]

Optional list of paywall IDs for filtering.

quizzesVersion[]string[]

Optional list of quiz versions for filtering.

fromstring date required

The start date for the graph data. Example: 2024-11-18.

tostring date required

The end date for the graph data. Example: 2024-11-25.

utm_source[]string[]

Optional UTM source for filtering.

utm_medium[]string[]

Optional UTM medium for filtering.

utm_campaign[]string[]

Optional UTM campaign for filtering.

utm_content[]string[]

Optional UTM content for filtering.

utm_term[]string[]

Optional UTM term for filtering.

utm_grouping'source_campaign_medium' | 'source_medium_campaign' | 'source_campaign_content' | 'source_campaign_content_term' | 'campaign' | 'content' | 'campaign_content' | 'quiz' | 'quiz_source' | 'quiz_source_campaign_content' | 'quiz_country' | 'quiz_platform' | 'country' | 'user_platform'

Grouping dimension for utmReport (ignored by other functions). UTM orders (source_campaign_medium, source_medium_campaign, source_campaign_content, source_campaign_content_term) split rows by campaign tags. campaign, content and campaign_content return a flat list of campaigns / ads. quiz, quiz_source, quiz_source_campaign_content, quiz_country and quiz_platform group by quiz first (each row also has quiz_id and quiz_name); ad spend columns are not available for them. country returns one row per user_country_code (visitor geo). user_platform returns one row per user_platform (ios / android / web, etc.). Combine with quizzes[], from, and to for a per-quiz visitor breakdown.

Multi-level groupings are drilled down one level at a time: the first request returns the first level, pass the values of the levels above (utm_source[], utm_campaign[], utm_medium[], utm_content[], drill_quiz_id[]) to get the next level.

drill_quiz_id[]integer[]

utmReport drill-down for the quiz groupings: the quiz whose next level (source / country / platform) is requested. Unlike quizzes[] it also tells the API to go one level deeper.

filter_utm_source[]string[]

utmReport only. Limits the whole report to these UTM sources. Unlike utm_source[], which is the drill-down value of the level above (and decides which level is returned), the filter_utm_* parameters never change the grouping level. The same applies to filter_utm_medium[], filter_utm_campaign[], filter_utm_content[] and filter_utm_term[].

filter_utm_medium[]string[]

utmReport only. Limits the report to these UTM mediums (see filter_utm_source[]).

filter_utm_campaign[]string[]

utmReport only. Limits the report to these UTM campaigns (see filter_utm_source[]).

filter_utm_content[]string[]

utmReport only. Limits the report to these UTM contents (see filter_utm_source[]).

filter_utm_term[]string[]

utmReport only. Limits the report to these UTM terms (see filter_utm_source[]).

drill_user_country_code[]string[]

utmReport drill-down below a country row (e.g. utm_grouping=country with split_by_day=1, or quiz_country): the country whose next level is requested. Also applies as a country filter.

drill_user_platform[]string[]

utmReport drill-down below a platform row (see drill_user_country_code[]).

split_by_dayboolean

utmReport only. Adds the visit day as the deepest level of any grouping: rows of the deepest level are split into one row per day (visit_day, YYYY-MM-DD in the project time zone, ascending). Purchases and revenue are attributed to the day of the visit, not the day of the payment; ad columns are matched by ad day where available.

step_event_namestring

stepAnswers only: funnel step event name as returned in the quizFunnel labels, e.g. Step 03 goals.

answers_user_propertystring

quizFunnel, throughFunnel, stepAnswers: answer key (user property name, the quiz screen block name or screen id). Together with answers_user_property_value narrows the funnel to the users who gave that answer.

answers_user_property_valuestring

The answer; for a multi-choice screen one of the selected options.

group_by'user_country_code'

Optional grouping, applies to functions[]=quizFunnel. When set to user_country_code, the funnel results are grouped by visitor country. The response for that function changes to { "group_by": "user_country_code", "groups": { "<COUNTRY>": { "labels": [...], "datasets": [...] } } }, where each country keeps the same chart shape as the ungrouped funnel (visitors with no country are bucketed under unknown). Without this parameter the funnel returns the original { labels, datasets } shape.

Response

Graph data retrieved successfully

successinteger
functionsobject

Map of requested function name to its payload. For utmReport with utm_grouping=country each row includes user_country_code. For utm_grouping=user_platform each row includes user_platform. Shared funnel fields include users_count, quizes_started, leads, paywall_views, initiate_checkouts, payment_initiated, subscriptions, total_revenue, conversion rates, arpu, and arppu.

Example response

{
  "success": 1
}

Changes

    • info

      added the new optional query request parameter answers_user_property

    • info

      added the new optional query request parameter answers_user_property_value

    • info

      added the new optional query request parameter drill_quiz_id[]

    • info

      added the new optional query request parameter drill_user_country_code[]

    • info

      added the new optional query request parameter drill_user_platform[]

    • info

      added the new optional query request parameter filter_utm_campaign[]

    • info

      added the new optional query request parameter filter_utm_content[]

    • info

      added the new optional query request parameter filter_utm_medium[]

    • info

      added the new optional query request parameter filter_utm_source[]

    • info

      added the new optional query request parameter filter_utm_term[]

    • info

      added the new optional query request parameter group_by

    • info

      added the new optional query request parameter split_by_day

    • info

      added the new optional query request parameter step_event_name

    • info

      added the new enum value campaign to the query request parameter utm_grouping

    • info

      added the new enum value campaign_content to the query request parameter utm_grouping

    • info

      added the new enum value content to the query request parameter utm_grouping

    • info

      added the new enum value country to the query request parameter utm_grouping

    • info

      added the new enum value quiz to the query request parameter utm_grouping

    • info

      added the new enum value quiz_country to the query request parameter utm_grouping

    • info

      added the new enum value quiz_platform to the query request parameter utm_grouping

    • info

      added the new enum value quiz_source to the query request parameter utm_grouping

    • info

      added the new enum value quiz_source_campaign_content to the query request parameter utm_grouping

    • info

      added the new enum value user_platform to the query request parameter utm_grouping