Manadge Extract API

The Manadge Extract API is an optional feature available for an additional fee. For more information, speak with your Triton Digital Client Success Manager.

The Manadge Extract API allows you to extract and export data from a Manadge workspace securely and efficiently. This documentation covers the available endpoints, response formats, and authentication methods.

The Extract API is based on the Export feature in the Manadge Workspace. Limits remains the same.

Authentication and Token Access

The API uses token-based authentication to ensure secure access. Tokens are generated on the Manadge UI Workspace and are dedicated to each user. These tokens are the primary means of authentication for accessing the API.

Token Usage

Once generated, the token needs to be manually saved by you (the user) as it won't be accessible later. You must include your token as Basic Auth with:

Email address used to log in to your Workspace
API Token generated on your workspace

Token Lifecycle

Expiration: Tokens expire every three months, for security purposes.
Refreshing: Tokens can be refreshed to extend their validity for another three months. This process is managed solely within the Manadge UI Workspace and cannot be done via the API.
Revoking: Tokens can be revoked if needed. Again, this action is managed solely within the Manadge UI Workspace.

Important: Since token management (refreshing or revoking) is handled exclusively within the Manadge UI Workspace and not via the API, you must ensure you refresh or revoke tokens as necessary through the appropriate page.

Endpoints

GET `/config`

The API provides an endpoint to retrieve configuration possibilities of a report. This endpoint allows you to obtain information about available dimensions, metrics, currencies, fees, and other criteria.

Retrieve Data Extraction Configuration
- Endpoint: GET /api/stats/extract/config
- Description: Retrieves information about dimensions, metrics, currencies, fees, and other criteria available for data extraction.

Example Request:

curl 'https://<workspace>.manadge.tritondigital.com/api/stats/extract/config' 
-u '<your email adress>:<your access token from api key>' 
-H 'Content-Type: application/json'

Example Response:

 "views": {
        "auction": {
            "groups": [
                "_all"
            ],
            "id": "auction",
            "name": "Auction",
            "dimensions": [
                {
                    "name": "Creative Language",
                    "null_name": "Creative Language Undefined",
                    "id": "creative_language",
                    "type": "dimension",
                    "source": "dimension",
                    "description": "Language of the creative (provided on the bid response)",
                    "can_filter": true
                },
                {
                    "name": "Device Global Region",
                    "null_name": "Device Global Region Undefined",
                    "id": "device_global_region",
                    "type": "dimension",
                    "source": "dimension",
                    "description": "Global territory of bid, retrieved from the IP address",
                    "can_filter": true
                },
                {
                    "name": "App Store URL",
                    "null_name": "App Store URL Undefined",
                    "id": "app_store_url",
                    "type": "dimension",
                    "source": "dimension",
                    "description": null,
                    "can_filter": true
                },
...
    },
  "bid": {
            "groups": [
                "_all"
            ],
            "id": "bid",
            "name": "Bid",
            "dimensions": [
                {
                    "name": "Bid Response Status",
                    "null_name": "Bid Response Status Undefined",
                    "id": "bid_response_status",
                    "type": "dimension",
                    "source": "dimension",
                    "description": null,
                    "can_filter": true
                },
                {
                    "name": "Creative Language",
                    "null_name": "Creative Language Undefined",
                    "id": "creative_language",
                    "type": "dimension",
                    "source": "dimension",
                    "description": "Language of the creative (provided on the bid response)",
                    "can_filter": true
                },
                {
                    "name": "Device Global Region",
                    "null_name": "Device Global Region Undefined",
                    "id": "device_global_region",
                    "type": "dimension",
                    "source": "dimension",
                    "description": "Global territory of bid, retrieved from the IP address",
                    "can_filter": true
                },"
        },
        ...
        }
    }
}

You must use the /config route to collect dimensions and metrics for your query. Do not use the dimensions and metrics in the example above, as these could change as the API evolves and some items might be specific to individual accounts.

POST `/extract`

The API provides an endpoint to generate reports by extracting ZIP files including:

Metadata of the report (Date, filters, dimensions, period, etc.)
CSV files with the data.

This endpoint allows you to specify parameters such as dates, currency, dimensions, metrics, order by, filters, and view type, for generating the report.

Generate Report
- Endpoint: POST /api/stats/extract
- Method: POST
- Description: Generates a report by extracting data in Parquet format based on specified parameters.
- Request Body:
  - dates*: A DateQuery object representing the date range for the report.
  - dimensions*: A list of Dimension objects specifying the dimensions for the report.
    - Must specify the id of the dimension retrieved from the /config query.
    - top*: Number of top values per dimension is manadory (max value 2000).
  - metrics*: A list of strings representing the metrics to be included in the report.
    - Must specify the id of the dimension retrieved from the /config query.
  - filters*: A dictionary containing key-value pairs for applying filters to the report data. It can be empty if no filters are applied.
  - order_by*: A string specifying the field to order the report data by.
  - view*: A string specifying the view type for the report data (i.e., Auction or bid)
  - fee (optional): A string representing the fee associated with the report data.
  - currency (optional): A string representing the currency for the report data.

* mandatory fields

Example Request:

curl --location 'https://{workspace}.manadge.tritondigital.com/api/stats/extract' \
-u '<your email adress>:<your access token from api key>'
--header 'Content-Type: application/json' \
--data '{
    "dates": {"from":"2024-04-29T00:00:00Z","to":"2024-04-30T00:00:00Z"},
    "dimensions":[{"name":"advertiser","top":100}],
    "metrics":["sumImpressions"],
    "order_by":"sumImpressions",
    "filters":{},
    "view":"auction"
}'

Example of the body of a request:

{
  "dates": {"from":"2024-04-29T00:00:00Z","to":"2024-04-30T00:00:00Z"},
  "currency":"USD",
  "dimensions":[{"name":"advertiser","top":10}],
  "metrics":["sumImpressions"],
  "order_by":"sumImpressions",
  "filters":{},
  "view":"bid"
}

Limits and Quotas

When using the Data Export API, you should be aware of the following limits and quotas:

30 Reports per Company per Day: Each company can generate up to 30 reports per day using the Data Export API.
Maximum 5 Dimensions per Report: Each report can include a maximum of five dimensions.
Unlimited Metrics per Report: There is no limit to the number of metrics that can be included in a report.
Additional security limits and quotas are currently being set up.