# Funnel API The **Data** **Studio** > **Funnel** page in the navigator uses an API that you can leverage to analyze funnel conversions in your own tools. For more information on the feature, see [Funnel](https://mediarithmics.gitbook.io/user-guide/data-studio/funnel). ## Retrieve dimensions values autocomplete `POST` `https://api.mediarithmics.com/v1/datamarts/:datamartId/user_activities_analytics` Use this call to get suggestions or autocomplete values for a dimension #### Query Parameters | Name | Type | Description | | ---------- | ------ | ---------------------- | | datamartId | number | The ID of the datamart | #### Request Body | Name | Type | Description | | -------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | metrics | array | Empty array | | dimension\_filter\_clauses | object | Dimensions filters clause to apply. | | dimensions | array | Names of the dimensions to retrieve. Usually only one dimension.Use multiple dimensions to get possible values of a dimension if the other dimension is set. For example, using the dimensions `TYPE` and `EVENT_TYPE` we can ask for the possible values of `EVENT_TYPE` if `TYPE` is `SITE_VISIT`. | | date\_ranges | array | Periods to analyze. Each date range is an object with a `start_date` and an `end_date`. | {% tabs %} {% tab title="200 " %} ```javascript { "status": "ok", "data": { "report_view": { "items_per_page": 100, "total_items": 7, "columns_headers": [ "type" ], "rows": [ [ "DISPLAY_AD" ], [ "EMAIL" ], [ "SITE_VISIT" ], [ "USER_SCENARIO_NODE_ENTER" ], [ "USER_SCENARIO_NODE_EXIT" ], [ "USER_SCENARIO_START" ], [ "USER_SCENARIO_STOP" ] ] } } } ``` {% endtab %} {% endtabs %} Here is a sample body payload ```javascript { "date_ranges": [ { "start_date": "2021-04-22T00:00:00", "end_date": "2021-04-29T23:59:59" } ], "dimensions": [ { "name": "TYPE" } ], "dimension_filter_clauses": { "operator": "OR", // OR or AND "filters": [ { "dimension_name": "TYPE", "operator": "LIKE", // LIKE, EXACT or IN_LIST "expressions": [ "" ] } ] }, "metrics": [] } ``` ## Submit a funnel for results `POST` `https://api.mediarithmics.com/v1/datamarts/:datamartId/user_activities_funnel` #### Path Parameters | Name | Type | Description | | ---------- | ------ | ---------------------- | | datamartId | number | The ID of the datamart | #### Request Body | Name | Type | Description | | ----- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | limit | number | When spliting a step on a specific field, sets the maximum values to be retrieved to optimize the query with what would be displayed.For example, set to 5 if you only show the 5 best channel IDs in the UI when splitting by channel ID to optimize the query. | | in | object | Period to query the funnel. Should be in the last 4 months maximum. | | for | object | List of steps in the funnel | {% tabs %} {% tab title="200 " %} ``` { "status": "ok", "data": { "global": { "total": 879879879, "steps": [ { "name": "Step 1", "count": 546546546, "interaction_duration": 0 }, { "name": "Step 2", "count": 897987984651, "amount": 1213213.27, "conversion": 11221, "interaction_duration": 515151 } ] }, "grouped_by": [] } } ``` {% endtab %} {% endtabs %} Here is a sample payload: ```javascript { "for": [ { "name": "Step 1", "filter_clause": { "operator": "OR", "filters": [ { "dimension_name": "TYPE", "not": false, "operator": "EXACT", "expressions": [ "DISPLAY_AD" ] } ] } }, { "name": "Step 2", "filter_clause": { "operator": "AND", "filters": [ { "dimension_name": "EVENT_TYPE", "not": false, "operator": "EXACT", "expressions": [ "$transaction_confirmed" ] }, { "dimension_name": "CHANNEL_ID", "not": false, "operator": "IN_LIST", "expressions": [ "8888", "6666" ] } ] } } ], "in": { "type": "DATES", "start_date": "2021-04-23", "end_date": "2021-05-01" }, "limit": 5 } ``` ## Dimensions You can build queries with the following dimensions: * Activity Date `DATE_TIME` * Activity Type `TYPE` * Ad Group Id `ORIGIN_SUB_CAMPAIGN_ID` * Brand `BRAND` * Channel Id `CHANNEL_ID` * Campaign Id `ORIGIN_CAMPAIGN_ID` * Category 1 `CATEGORY1` * Category 2 `CATEGORY2` * Category 3 `CATEGORY3` * Category 4 `CATEGORY4` * Creative Id `ORIGIN_CREATIVE_ID` * Device Brand `DEVICE_BRAND` * Device Browser `DEVICE_BROWSER_FAMILY` * Device Carrier `DEVICE_CARRIER` * Device Form Factor `DEVICE_FORM_FACTOR` * Device Model `DEVICE_MODEL` * Device OS `DEVICE_OS_FAMILY` * Has conversion `HAS_CONVERSION` * Has clicked `HAS_CLICKED` * Has bounced `HAS_BOUNCED` * Event type `EVENT_TYPE` * Is in segment `SEGMENT_ID` * Campaign Id `CAMPAIGN_ID` * Goal Id `GOAL_ID` * Product Id `PRODUCT_ID` ## Dimensions filters clause This object represents a group of filters to apply in a request. It has: * An `operator` field to apply either an `AND` or an `OR` between the filters * A `filters` array for the list filters to apply. For more information, see [Dimensions filters](#dimensions-filter). ```javascript "filter_clause": { "operator": "OR", // OR or AND "filters": [ ... ] } ``` ## Dimensions filter This object represents a filter in a filters clause. It has; * A `dimensions_name` field to select the dimension it applies on. For more information, see [Dimensions](#dimensions). * A `not` boolean field to apply boolean logic * An `operator` field to select one of the following queries: * `EXACT` will force the dimension to match the first expression set * `LIKE` will allow the dimension to only contain the first expression set * `IN_LIST` will allow the dimension to be one of the expressions set * A list of `expressions` representing the keywords to search for. ### Examples ```javascript // TYPE should be DISPLAY_AD { "dimension_name": "TYPE", "not": false, "operator": "EXACT", "expressions": [ "DISPLAY_AD" ] } // TYPE should contain SITE // SITE_VISIT activities will be used { "dimension_name": "TYPE", "not": false, "operator": "LIKE", "expressions": [ "SITE" ] } // TYPE should not contain SITE { "dimension_name": "TYPE", "not": true, "operator": "LIKE", "expressions": [ "SITE" ] } // CHANNEL_ID should be either 8888 or 6666 { "dimension_name": "CHANNEL_ID", "not": false, "operator": "IN_LIST", "expressions": [ "8888", "6666" ] } ```