# 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](/querying-your-data/funnel-api.md#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](/querying-your-data/funnel-api.md#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"
]
}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.mediarithmics.io/querying-your-data/funnel-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.