# Api
To integrate Alviss AI into your existing systems, we provide a comprehensive API. The full API documentation is available at [here](../api).
To access the API documentation, you must first sign in to the Alviss AI platform at [https://app.alviss.io](https://app.alviss.io).
## Authentication [#authentication]
All API requests require authentication using an access token. For details on creating an access token, refer to the [Create Access Token](#create-access-token) section below.
Once you have your access token, include it in the `Authorization` header of your requests as a Bearer token. Here's an example using `curl` (replace `YOUR-TOKEN` with your actual token):
```bash
curl --request GET \
--url "https://api.alviss.io/v1/team/teams" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "Accept: application/json"
```
## Managing Access Tokens [#managing-access-tokens]
You can manage your access tokens by navigating to [https://app.alviss.io/-/user#access-tokens](https://app.alviss.io/-/user#access-tokens). Alternatively, click on your profile picture in the top-right corner of the Alviss AI platform, select **Your Account** from the menu, and then go to the **Access Tokens** tab.
### Create Access Token [#create-access-token]
1. Click the **Create New Token** button.
2. In the modal that appears, fill in the following fields:
* **Name**: A descriptive name for your token (e.g., "Integration Token").
* **Expires At**: The expiration date and time for the token. For security, set an expiration that aligns with your needs—we recommend limiting it to when your task is complete. Tokens can expire up to 365 days from creation.
3. Submit the form. Your new access token will be displayed only once—copy and store it securely immediately, as it will not be visible again after closing the modal.
### Revoke Access Token [#revoke-access-token]
To revoke a token, locate it in the list of access tokens and click the **Revoke** button next to it. This immediately invalidates the token, preventing further use.
# Activities
## Overview [#overview]
The Activities dashboard is your primary tool for visualizing and analyzing raw data within Alviss AI. It generates dynamic overviews for each file in your active [Dataset](./Data/Datasets), enabling you to track essential metrics like total sales, latest investments, or engagement trends. This dashboard supports exploratory data analysis (EDA), helping identify patterns, anomalies, and relationships before advancing to modeling or insights.
By default, Activities uses the current \[Active Dataset]\(./Data/Datasets#Active Dataset). To ensure consistency between Activities and the [Effect](./Effect) dashboard, adjust the `Activities - Dashboard Data Source` in your [project settings](./Projects).
## Key Features [#key-features]
* **Overview Dashboards:** Automatically created for every file in your Dataset, these summarize key data points, trends, and aggregates (e.g., total and latest values for sales or investments).
* **Graphs and Visuals:** Includes a range of charts, such as line graphs for time series, bar charts for comparisons, and heatmaps for correlations, making EDA intuitive and efficient.
* **Tooltips:** Hover over any graph, metric, or element for detailed explanations, contextual info, and raw values, enhancing understanding without cluttering the view.
Remember to use [Filtering](./Filtering) for more accurate data analysis, such as isolating specific regions, products, or time periods.
## Best Practices [#best-practices]
* **Data Validation:** Before proceeding to model building, inspect for outliers, missing values, or inconsistencies here. Use visuals to spot trends and tooltips for deeper dives.
* **Consistency Settings:** If your workflow involves both Activities and Effect dashboards, update project settings to use the same Dataset, ensuring aligned insights.
* **Exploratory Workflow:** Start with broad overviews, then apply filters to drill down. Combine with Data Explorer for variable-specific analysis.
* **Team Collaboration:** Share dashboard views or export visuals for reports, leveraging [team access](./Teams) for collaborative reviews.
Before building models, it's important to thoroughly check your data for any outliers or missing observations. Ensuring data quality will improve the accuracy and reliability of your results.
# Correlation
## Overview [#overview]
The Correlation tool calculates how strongly variables in your dataset are related to each other. It computes three correlation coefficients — Pearson, Spearman, and Kendall — between your chosen targets and variables, helping you identify linear and non-linear relationships.
The dataset must have at least **5 epochs** to run correlation analysis.
## How to Run [#how-to-run]
1. Open **Correlation Metrics** from the navigation.
2. Select **Modeling Combinations** — one or more Country/Region/Grouping triplets.
3. Select **Targets** — the variables to correlate against (defaults to the Sales group).
4. Select **Variables** — the candidate variables (defaults to the Price group).
5. Click **Get Correlation Metrics**.
## Reading the Results [#reading-the-results]
### Table View [#table-view]
A sortable, filterable table with columns: Target, Variable, Combination, Pearson, Spearman, and Kendall. Expand a row to see additional detail.
### Matrix View [#matrix-view]
A heatmap showing pairwise correlations between all selected variables at a glance. Stronger correlations appear as more intense colors.
### Correlation Methods [#correlation-methods]
| Method | Measures | Best for |
| ------------ | ----------------------------------- | ----------------------------------------------- |
| **Pearson** | Linear relationship | Continuous variables with a linear trend |
| **Spearman** | Monotonic relationship (rank-based) | Ordinal data or non-linear but monotonic trends |
| **Kendall** | Concordance (rank-based) | Small samples or data with many tied values |
## Tips [#tips]
* High Pearson but low Spearman may indicate outliers are driving a spurious linear correlation.
* Use correlation results alongside [Feature Importance](./Feature%20Importance) to distinguish between correlated variables and truly predictive ones.
* Check for multicollinearity (high correlations between predictor variables) before model building.
## See Also [#see-also]
* [Feature Importance](./Feature%20Importance) — rank variables by predictive power
* [Data Explorer](./Data%20Explorer) — visually inspect variable relationships
# Data Explorer
## Overview [#overview]
The Data Explorer lets you visually inspect variables from your datasets, uploads, or external data sources. It provides four views — individual variable trends, multi-variable comparisons, scatter plots, and descriptive statistics — all filterable by modeling combination.
## Source Selection [#source-selection]
Before exploring, select a data source (dataset or upload). This populates the available variables and modeling combinations. You can then pick which variables to inspect and optionally narrow down to specific Country/Region/Grouping combinations.
## Tabs [#tabs]
### Each Variable [#each-variable]
Displays one sub-tab per selected variable with two visualizations:
* **Explore by Date** — a line plot of the variable's values over time.
* **Country-Region-Grouping Breakdown** — a sunburst chart showing the variable's distribution across combinations (unaffected by the combination filter).
### Variables Comparison [#variables-comparison]
Shows all selected variables on a single line plot over time. Hover over a date to see a breakdown in an accompanying bar and pie chart.
If two or more variables are selected, a **correlation matrix** is also displayed below the line plot.
### Scatter [#scatter]
Plots variables against each other. If more than three variables are selected, a secondary selector lets you pick up to three for the plot. The chart adapts automatically:
* **1 variable** — distribution plot
* **2 variables** — standard scatter plot
* **3 variables** — 3D scatter plot
If the selected variables have no overlapping dates, a message is shown instead.
### Statistics [#statistics]
A sortable table with one row per variable showing: Max, Min, Sum, Mean, Median, Standard Deviation, and Range.
## Aggregation [#aggregation]
On the Variables Comparison and Scatter tabs, an aggregation selector controls how values are combined across modeling combinations. Options: **sum**, **mean**, **min**, **max**.
## Tips [#tips]
* Start with the **Each Variable** tab to spot anomalies before comparing variables.
* Use the **Statistics** tab for a quick sanity check on data ranges and distributions.
* Narrow down to a single modeling combination when comparing variables to avoid aggregation effects masking patterns.
## See Also [#see-also]
* [Activities](./Activities) — track modeling activity across your project
* [Filtering](./Filtering) — learn about combination filtering
# Effect
The Effect dashboard provides a comprehensive overview of your active [Attributionset](./Attributions/Intro.md). Here, you can visualize how various drivers impact your commercial objectives, all based on your AI model and data.
**Key Features:**
* **Full Breakdown:** Gain detailed insights into how each driver influences your KPIs, helping you understand the relative importance and impact of different factors.
* [Filtering](./Filtering): Utilize filters to focus on specific variables, regions, or time periods, ensuring your analysis is relevant and precise.
* **Tooltips:** Hover over elements in the dashboard to access tooltips, which offer additional context and explanations for a clearer understanding of the data presented.
By leveraging these features, you can make the most of the Effect dashboard to support data-driven decision-making and strategic planning.
# Feature Importance
## Overview [#overview]
Feature Importance measures how much each variable contributes to predicting a target. It fits a gradient boosting model and reports both built-in importance scores and permutation importance across multiple quantiles (Q10, Q25, Q50, Q75, Q90), giving you a sense of each variable's impact and the stability of that estimate.
The dataset must have at least **5 epochs** to run feature importance.
## How to Run [#how-to-run]
1. Open **Feature Importance** from the navigation.
2. Select **Modeling Combinations** — choose one or more Country/Region/Grouping triplets.
3. Select **Targets** — the variables you want to predict (defaults to the Sales group).
4. Select **Variables** — the candidate predictors (defaults to all variables except Sales and Events).
5. Click **Get Feature Importance**.
## Reading the Results [#reading-the-results]
### Table [#table]
The results table shows one row per combination × target × variable with columns for each quantile (Q10–Q90). It is sorted by Q50 descending by default.
You can:
* **Filter** by combination, target, or variable group.
* **Sort** any column.
* **Toggle columns** with the Show/Hide Columns button.
### Plots [#plots]
Plots are organized into tabs by variable group (Media, Price, Distribution, etc.). Each tab contains scatter plots — one per target — showing the quantile spread for every variable.
## Create Model Shortcut [#create-model-shortcut]
Select rows in the table and click **Create Model** to jump directly into model building with those variables pre-selected. This is a convenient way to go from exploration to modeling.
## Tips [#tips]
* A high Q50 with a wide Q10–Q90 spread means the variable is important but its ranking is unstable — investigate further.
* Compare importance across multiple targets to find variables that are broadly predictive vs. target-specific.
* Use this as a pre-modeling step to reduce the variable set before building a model.
## See Also [#see-also]
* [Correlation](./Correlation) — measure pairwise relationships between variables
* [Models](./Models) — build and manage models
# Filtering
Filtering is essential for accurate data analysis. It allows you to focus on specific variables, such as a particular country, region, or product, ensuring that you capture important details and trends that might be hidden in aggregated data.
**[Activities](./Activities.md) Dashboard:**
* **Filter by Variables:** Select specific variables like Country, Region, or Grouping to drill down into your data and conduct a detailed analysis.
* **Date Range Filters:** Modify the time period to examine trends across different time frames, enhancing the precision of your analysis.
**[Effect](./Effect.md) Dashboard:**
* **Filter by Drivers:** Isolate particular drivers to assess their impact on your KPIs, helping you determine which factors are most significant.
* **Regional Filters:** Focus on data for specific countries or regions to understand variations in geographic performance.
* **Filter by Responses:** Analyze individual KPIs separately to achieve a more accurate and detailed assessment.
Effectively using filters ensures that your analysis is targeted and insightful, enabling you to draw precise and actionable conclusions from your data.
# Optimizations
Hand-tuning [simulations](./Simulations) and [predictions](./Predictions) for maximum effectiveness can be tedious and time-consuming. Instead, Alviss AI provides an optimization feature, allowing you to achieve optimal outcomes efficiently by setting constraints and letting the system do the heavy lifting.
This tool automatically adjusts selected variables to meet your goals—whether maximizing KPIs like revenue or minimizing costs—while respecting real-world limits. Optimizations build on your active [Dataset](./Data/Datasets.md) and models, producing scenario-based recommendations for strategic planning, such as budget allocation or resource distribution.
## Mode [#mode]
### Dynamic Optimization [#dynamic-optimization]
Dynamic optimization seeks to find the best possible value given the constraints set. It automatically adjusts the input variables to maximize or minimize the outcome based on your specified goals and constraints.
### Goal-Driven Optimization [#goal-driven-optimization]
In goal-driven optimization, you set a specific target to achieve. This can be an absolute value (e.g., exactly X number of sales) or a value relative to the baseline (e.g., Y more sales than the baseline).
## Date Range [#date-range]
Choose the date range for the input you want to optimize. You can also decide whether to include pre and post periods in your analysis. Depending on your model, some variables, like media, can have a carry-over effect on your KPIs. This means the investment made in a specific period might affect your KPIs in later periods.
* **Pre-period:** Including the pre-period allows you to consider input data before the optimization period, resulting in more accurate predictions.
* **Post-period:** Including the post-period makes the optimization more accurate by accounting for the effects on KPIs that your variables might have after the optimization period.
## Target [#target]
Specify the KPIs for optimization.
* **Dynamic Optimization:** Choose whether you want your target to be maximized or minimized.
* **Goal-Driven Optimization:** Set a goal you want to achieve and decide if you want it to be relative (the increase or decrease from the observed value) or absolute.
## Optimization Variables [#optimization-variables]
Select the input variables that should be optimized. Variables not selected for optimization will retain their values from the dataset.
## Constraints [#constraints]
Set conditions for the sum of a variable over time. Specify whether the variable should be greater than, less than, or equal to a specific value. If multiple variables are selected, their values will be summed together.
* **Use Case:** Setting a total media budget and combining it with a maximum spend for individual media channels across all time points.
### Boundary Constraints [#boundary-constraints]
Boundary constraints are set for each individual time point and include the following types:
* **Max:** The maximum value the variable can become.
* **Threshold Max:** If the value exceeds the `Threshold Max`, it will jump to the `Max` value. Note that `Max` must be set, and `Threshold Max` must be less than the `Max` value.
* **Threshold Min:** If the value falls below the `Threshold Min`, it will jump to the `Min` value. Note that `Min` must be set, and `Threshold Min` must be greater than the `Min` value.
* **Min:** The minimum value the variable can become.
## Directions [#directions]
For goal-driven optimizations, you can set directions for variables to specify the desired trend while achieving the set target. This includes:
* **Minimize:** Make the variable as small as possible.
* **Maximize:** Make the variable as large as possible.
* **Neutral:** No fixed direction, or simply do not set a direction for the variable.
* **Use Case:** Setting a media variable to `Minimize` would mean trying to hit your target while spending as little as possible on media.
## Running an Optimization [#running-an-optimization]
1. **Navigate to Optimization:** Go to the Optimization section in the Alviss AI platform.
2. **Select Mode:** Choose between dynamic optimization and goal-driven optimization.
3. **Set Variables and Constraints:** Select the input variables to be optimized and apply any equality, inequality, or boundary constraints.
4. **Configure Directions (if applicable):** For goal-driven optimization, set the desired directions for the variables.
5. **Run Optimization:** Click on the "Submit" button to execute the optimization process.
## Understanding the Results [#understanding-the-results]
When the optimization completes, Alviss AI provides detailed results that include:
* **Optimized Values:** The best possible values for the input variables given the constraints and goals.
* **Outcome Analysis:** A comparison of the optimized scenario against the baseline, highlighting the differences and impacts of the optimization.
# Predictions
Predictions in Alviss AI empower you to forecast future outcomes based on customizable drivers, enabling proactive preparation and informed strategic planning. This feature leverages your trained models to project key performance indicators (KPIs) like sales, demand, revenue, or customer metrics under specified conditions. Ideal for scenarios such as inventory optimization, sales forecasting, or budgeting, Predictions focus on absolute outcomes over time, complementing [Simulations](./Simulations), which emphasize comparative "what-if" differences.
By adjusting variables like marketing spend, pricing, or external factors, you can generate time-series forecasts with uncertainty estimates, helping you anticipate trends and mitigate risks.
## Setting Up Predictions [#setting-up-predictions]
### Variables [#variables]
Any variable from your dataset can be controlled and set to custom values to explore their influence on outcomes. Follow these steps to configure:
1. **Navigate to Predictions:** Access the Predictions section via the side menu or directly at [https://app.alviss.io/predictions](https://app.alviss.io/predictions).
2. **Add Variables:** Select variables of interest (e.g., advertising spend, promotions, or economic indicators).
3. **Set Variable Values:** Define values for each time point, providing granular control over inputs.
* **Example:** To forecast sales, set advertising spend to varying levels across time periods and observe the projected impact.
For a detailed walkthrough of the variable modification interface—including patterns, scaling, quick actions, and granular edits—see \[Modifying Scenario and Baseline]\(Simulations#Modifying Scenario And Baseline). The Prediction interface shares the same intuitive controls.
### Multiple Scenarios (Optional) [#multiple-scenarios-optional]
Predictions support running multiple scenarios in parallel for side-by-side comparison:
* Copy an existing scenario to iterate on variations.
* Add new scenarios from scratch to test diverse assumptions.
This allows efficient evaluation of alternatives, such as different budget levels or market conditions.
## Running Predictions [#running-predictions]
1. **Configure Inputs:** Finalize variable settings and any additional parameters (e.g., date range).
2. **Run Predictions:** Click "Run Predictions" to process in the background. Results appear once complete.
## Understanding Prediction Results [#understanding-prediction-results]
Results provide a comprehensive view of forecasts:
* **Predicted Values:** Core outcomes based on your inputs, such as projected sales totals.
* **Time Series Analysis:** Graphs showing how predictions evolve over time.
* **Confidence Intervals:** Bands indicating uncertainty, helping assess reliability (e.g., likely ranges for outcomes).
Visualizations include totals, per-period trends, cumulative sums, and toggles for tables, uncertainty display, and [Filtering](./Filtering). Tooltips offer additional context on hover.
## Utilizing Prediction Insights [#utilizing-prediction-insights]
Leverage Predictions to drive business value:
* **Prepare for Future Demand:** Forecast inventory needs to reduce stockouts or overstock.
* **Optimize Sales Strategies:** Identify high-impact drivers for targeted interventions.
* **Strategic Planning:** Inform investments, resource allocation, and scenario planning with evidence-based projections.
Integrate with features like [Attributions](./Attributions/Intro.md) for impact breakdowns, [Optimizations](./Optimizations) for recommendations, and [Response Curves](./Response%20Curves) for sensitivities. For a hands-on guide, see the [Run a Prediction](../tutorials/Getting%20Started/Run%20a%20Prediction) tutorial.
# Projects
Alviss AI organizes workflows around projects, each serving as a self-contained workspace for managing datasets, models, and derived insights. Users have flexibility in structuring projects to suit their analysis needs—for instance, creating separate projects per country for isolated views or a single global project for cross-regional visualizations. A key constraint is that all data within a project must maintain uniform granularity (e.g., daily, weekly) to ensure compatibility.
There will be a cap on the total number of allowed projects for a team; this is tied to the agreed pricing package for the team.
## Viewing and Switching Projects [#viewing-and-switching-projects]
Access the project list via the side menu, where all team projects are displayed. This interface allows seamless switching between projects. All team members have full access to every project in the team.
* Navigate by clicking the Alviss AI logo to reach the project list page.
* Alternatively, use the project switcher dropdown menu and select "All Projects" at the bottom.
## Creating a Project [#creating-a-project]
One needs to have the user role of `Manager` or `Admin` in order to be able to create new projects and to access project settings.
To create a new project:
1. From the project list, click "New Project."
During creation, specify:
* **Project Name:** A descriptive identifier for the project.
* **Data Periodicity:** The time granularity (e.g., daily, weekly) as defined in [Data Periodicity](./Data/Format/Periodicity). This setting is permanent and cannot be altered later.
Projects created within a team are immediately accessible to all team members. For team management details, see [Teams](./Teams).
## Project Settings [#project-settings]
Project settings allow modifications to core attributes and dashboard behaviors. Access settings from the project dashboard or list.
### General Modifications [#general-modifications]
* Update the project name or display currency (note: currency changes affect only the unit symbol, not underlying values).
* Delete the project if it's no longer needed (this action is irreversible and removes all associated datasets, models, and insights).
### Dashboard Configuration [#dashboard-configuration]
Customize dashboard experiences to align with team workflows and data presentation needs.
#### Activities Dashboard Data Source [#activities-dashboard-data-source]
Select the dataset source for the [Activities](./Activities) dashboard:
* **Same as Effects Dashboard:** Ensures consistency between [Activities](./Activities) and [Effect](./Effect) dashboards by using the active attributionset-linked dataset.
* **Use Active Dataset:** Displays the most recent \[Active Dataset]\(./Data/Datasets#Active Dataset) ideal for previewing new data before attributions are generated.
#### Default Filters [#default-filters]
Define preset filters applied automatically upon loading dashboards. These are visible and editable by users, making them suitable for standard views (e.g., excluding secondary KPIs like "Revenue" to avoid double-counting in sales-based plots). Configurable separately for [Activities](./Activities) and [Effect](./Effect) dashboards.
#### Pre-Filters [#pre-filters]
Apply hidden filters that process data before it reaches the dashboards. These are invisible to end users, useful for permanently excluding sensitive or irrelevant variables without affecting user interactions.
#### Menu Permissions [#menu-permissions]
Control visibility of dashboard elements to tailor the user experience:
* Disable specific tabs or sections in [Activities](./Activities) and [Effect](./Effect) dashboards.
* Hide individual plots or areas via the floating button in the bottom-right corner of the dashboard.
Changes apply to the current page; navigate to other pages to adjust their elements. These settings ensure team members see only relevant information, enhancing focus and security.
For related workflows, refer to [Getting Started](../tutorials/Getting%20Started) or [Datasets](./Data/Datasets). If integrating programmatically, see [API](./API) for project endpoints.
# Response Curves
Response Curves provide a visual representation of how a specific variable affects your KPIs (Key Performance Indicators). This tool allows you to explore the impact of varying a particular variable within a defined range, offering valuable insights into the relationship between the variable and your business outcomes, including identifying the saturation point where increasing the variable's value no longer enhances the effect on your KPIs.
### Steps to Generate a Response Curve [#steps-to-generate-a-response-curve]
1. **Select a Country, Region, Grouping, Model, and a Dataset**
2. **Select a Variable of Interest:**
* Choose the variable whose effect on your KPIs you want to analyze.
3. **Set Minimum and Maximum Values:**
* Define the range for the chosen variable by setting a minimum and maximum value. These values will be used to run the simulations.
4. **Advanced**:
* Select number of posterior samples.
* Select a Date Range to be used.
5. **Submit:**
* Alviss AI will run a set of simulations using values between the defined minimum and maximum. For each value within this range, the app will calculate the difference in prediction compared to the prediction using the minimum value. The result is the predicted effect.
6. **View the Response Curve:**
* Go to the Response Curve's details page to visualize the results.
* The obtained effects are plotted as a function of the variable's values. The response curve will show how changes in the variable influence your KPIs.
### Benefits of Using Response Curves [#benefits-of-using-response-curves]
* **Understanding Impact:** Gain a clear understanding of how specific variables affect your business outcomes.
* **Identifying Trends:** Visualize trends and relationships that may not be apparent from raw data alone.
* **Identifying Saturation Point:** Determine the point at which increasing the variable's value no longer results in an increase in your KPIs, helping to avoid unnecessary investments.
* **Informed Decision-Making:** Use the insights from response curves to make data-driven decisions and optimize your strategies.
### Example Use Case [#example-use-case]
If you are analyzing the impact of marketing spend on sales, you can use a response curve to see how different levels of marketing investment affect your sales KPIs. By setting the minimum marketing spend to \$0 and the maximum to \$100,000, you can observe how incremental increases in marketing spend influence sales. The response curve can also help you identify the saturation point, where further increases in marketing spend do not lead to additional sales, allowing you to determine the optimal marketing budget.
Response Curves are a powerful feature in Alviss AI, enabling you to explore and visualize the effects of specific variables on your KPIs comprehensively. Use this tool to enhance your analysis, identify key inflection points, and make more informed, data-driven decisions.
# Simulations
Unlike [Predictions](./Predictions), which emphasize absolute future outcomes for tasks like demand forecasting, Simulations highlight differences between scenarios to reveal optimal actions and synergies across activities.
## Scenario vs. Baseline [#scenario-vs-baseline]
At the heart of Simulations is the comparison between a **scenario** and a **baseline**:
* **Scenario:** The experimental condition you wish to test, such as increasing media investments by a specific amount or pattern.
* **Baseline:** The reference condition for comparison, like zero investment or maintaining historical levels.
This setup isolates the effects of changes, answering questions like: "What additional revenue would result from boosting marketing spend compared to the status quo?"
## Running a Simulation [#running-a-simulation]
To create and run a Simulation:
1. **Navigate to Simulations:** Access the Simulations section via the side menu in the Alviss AI platform.
2. **Set Variables:** Select the variables to include (e.g., media channels, pricing, or macroeconomic factors). Unselected variables default to their dataset values.
3. **Configure Scenario and Baseline:**
* Define values, patterns, and scaling for each variable in both the scenario and baseline.
* **Scenario Example:** Set media investments to a targeted total spend with a historical pattern.
* **Baseline Example:** Set media investments to zero to measure the absence of activity.
4. **Run the Simulation:** Click "Run Simulation" to process it in the background. Results will be available once complete.
## Modifying Scenario and Baseline [#modifying-scenario-and-baseline]
The variable configuration interface is designed for quick setup while offering granular control over each variable at every time point. Below is a walkthrough of key functionalities, with numbered references to the interface elements.
1. For each variable group, decide whether to enter values as the `sum` or the `mean` over the time period. For media investments, sum is usually preferred; for variables like weather, mean is often more relatable (think temperature).
2. Quick action buttons allow you to set the entire baseline to zero, the historical minimum per variable, or the historical maximum per variable.
3. The same quick actions as in 2, but for the scenario.
4. Control the pattern of the variable's behavior:
* **Historical:** Mirrors the exact historical pattern, scaled up or down based on your specified value.
* **Constant:** Uniform value every epoch, summing (or averaging, depending on setting in 1) to the specified value.
* **Custom:** Applies if you manually adjust values.
5. Choose how to scale the pattern to match your set value:
* **Additive:** Shifts values up or down by a constant—useful for variables like unemployment rate or temperature.
* **Multiplicative:** Applies proportional scaling—ideal for preserving zeros in patterns like media spend.
6. By default, values are enforced within historical min and max bounds. To simulate beyond these (e.g., for exploratory scenarios), enable this option for the variable group to allow values outside historical limits.
7. Enter the baseline value for the entire period, as either the `Sum` or the `Mean` based on the setting in 1.
8. Same as 7, but for the scenario.
9. At the variable level, control the pattern (as in 4), scaling behavior (as in 5), historical bounds adherence (as in 6), or remove the variable from the simulation (it will then use dataset defaults).
10. Expand a variable to view its values per data point—useful for testing patterns. The view includes historical min/max in the plot, plus a statistical summary of baseline and scenario settings.
11. Manually drag points on the graph to set specific values; this switches the pattern to `Custom`.
12. Within each variable's scenario or baseline, use buttons to shift values up/down by a percentage, set to min/max, reset, or load data from a different time period.
If setting values outside historical bounds triggers a warning, resolve it by enabling out-of-bounds, deforming the pattern to fit, or enforcing bounds strictly.
## Understanding the Results [#understanding-the-results]
Once complete, results are displayed in three tabs for easy analysis:
* **Scenario Results:** Outcomes under the experimental conditions.
* **Baseline Results:** Outcomes under the reference conditions.
* **Difference Analysis:** The delta (Scenario minus Baseline), emphasizing incremental impacts like added revenue or reduced churn.
Visualizations include totals, time-series trends, cumulative effects, and uncertainty estimates. Switch between graphs and tables, apply [Filtering](./Filtering), and hover for tooltips.
## Utilizing Simulation Insights [#utilizing-simulation-insights]
Simulations drive strategic optimization by revealing potential outcomes:
* Compare media plans to maximize ROI.
* Test pricing adjustments for impact on sales and churn.
* Evaluate synergies between marketing and external factors.
Integrate with features like [Attributions](./Attributions/Intro.md) for impact breakdowns, [Optimizations](./Optimizations) for budget recommendations, and [Response Curves](./Response%20Curves) for variable sensitivities. For a step-by-step example, see the [Run a Simulation](../tutorials/Getting%20Started/Run%20a%20Simulation) tutorial.
# Teams
Alviss AI facilitates collaborative machine learning workflows by organizing all activities around team entities. This structure ensures shared access to resources, enabling efficient teamwork in model development and deployment.
## Team Structure [#team-structure]
* **Single-User Teams:** Individual users operate within a self-contained team, granting full access to platform features equivalent to those in larger groups.
* **Asset Ownership:** Resources including compute, storage, and datasets are team-owned, not user-specific, allowing universal access among members.
* **Collaboration Model:** Teams support joint project work, insight sharing, and collective contributions to machine learning pipelines.
## Resource Management [#resource-management]
### Compute and Storage [#compute-and-storage]
* **Shared Compute:** Teams allocate processing resources dynamically based on workload demands, promoting efficient utilization.
* **Centralized Storage:** All data and artifacts reside in team-level storage, providing seamless access and reducing data silos.
### Data Handling [#data-handling]
* **Access Controls:** Team members have read/write permissions on all team data, streamlining collaborative analysis and modeling.
* **Consistency Assurance:** Central storage eliminates version conflicts and duplicate data, maintaining data integrity.
### Subscriptions [#subscriptions]
* **Team-Level Billing:** Platform subscriptions are applied at the team scope, with features and quotas shared across all members rather than per individual.
## Advantages [#advantages]
* **Improved Teamwork:** Enables real-time collaboration on models, experiments, and deployments.
* **Efficiency Gains:** Optimizes resource use by avoiding redundancy in compute and storage.
* **Data Reliability:** Ensures uniform access to current data, enhancing model accuracy and decision quality.
## Member Administration [#member-administration]
To administer team membership:
1. **Access Member List:** Navigate to the "Team Members" view for an overview of current participants.
2. **Invite Users:** Use the invitation tools to add new members via email or direct links.
3. **Remove Users:** Revoke access for inactive or departing members through the management interface.
## Exiting a Team [#exiting-a-team]
To leave a team:
1. **Open Settings:** Access "Team Settings" from the navigation menu.
2. **Initiate Exit:** Select the "Leave Team" option and confirm.
## Team Deletion [#team-deletion]
To permanently delete a team:
1. **Open Settings:** Access "Team Settings" from the navigation menu.
2. **Initiate Deletion:** Select the "Delete Team" option and confirm, noting that this action is irreversible and removes all associated resources.
For integration with external systems, refer to the [API Documentation](./API) on team endpoints. See also [Projects](./Projects) for managing team-shared workspaces.
# Introduction
Alviss AI can be accessed at [https://app.alviss.io](https://app.alviss.io).
The [Alviss Ai](https://app.alviss.io) is a platform for Holistic Business Measurement and Optimization that can be used to gain insights in to various drivers such as
* pricing
* marketing
* distribution
* macro economy
* customer experience
on business KPIs such as Sales and Churn.
## Data-driven decision making [#data-driven-decision-making]
Business science involves analyzing data and using ML models to make informed decisions about how to grow a business. By using data to guide decision making, businesses can make more informed and accurate decisions about things like pricing, marketing, and operations.
## Identifying new opportunities [#identifying-new-opportunities]
Business science can help businesses identify new opportunities for growth by analyzing data on market trends and customer behavior. This can include identifying new customer segments to target or identifying untapped markets to enter.
## Optimizing business processes [#optimizing-business-processes]
Business science can help businesses optimize their operations by identifying bottlenecks and inefficiencies in their processes. This can lead to cost savings and increased efficiency, which can help drive business growth.
## Improved customer experience [#improved-customer-experience]
By using data to understand customer needs and preferences, businesses can improve the customer experience and increase customer loyalty. This can lead to repeat business and word-of-mouth marketing, both of which can contribute to business growth.
# Working With Attributions
### Creating a New Attribution [#creating-a-new-attribution]
To create a new attribution in Alvíss AI, follow these steps:
1. **Select a Model:**
* Choose models that correspond to the countries, regions, and groupings of interest. These models will be used to calculate the impact of each variable on the Key Performance Indicators (KPIs) for the selected areas.
2. **Choose a Date Period:**
* Specify the date period you want to include in the attribution analysis.
3. **Default Settings vs. Advanced Settings:**
* You can create an attribution using Alvíss AI's default settings, which are pre-configured for general use.
* For more customized attributions, navigate to the `Advanced` section. Here, you can:
* Select the number of samples drawn from a posterior distribution.
* Set baseline values for each variable.
* Note that increasing the number of samples will extend the calculation time.
### Why Change Baseline Values [#why-change-baseline-values]
Alvíss AI's attribution calculations use a default set of baseline values designed to work well for most business cases. However, as an advanced user, you might want to customize these baseline values to better align with your specific business context and goals.
**Default Baseline Values:**
The default baseline value depends on the variable group. The following table shows the default baseline for each group:
| Variable Group | Default Baseline |
| ----------------------- | ---------------- |
| Media | 0 |
| Competitor Media | 0 |
| Competitor Distribution | 0 |
| Customer Experience | 0 |
| Distribution | 0 |
| Visits | 0 |
| Sales | 0 |
| Events | 0 |
For variables that do not belong to one of the groups above, the default baseline is the minimum observed value of that variable. If a variable has been explicitly assigned a custom baseline, that value always takes precedence.
**Customizing Baseline Values:**
* **Tailor to Your Business:** By adjusting the baseline values, you can make the attribution analysis more relevant to your unique business conditions and challenges.
* **Leverage Your Expertise:** Use your industry knowledge and insights to set baseline values that reflect realistic scenarios and benchmarks for your business.
* **Enhance Precision:** Custom baseline values allow for more precise and meaningful impact assessments, improving the accuracy of your decision-making process.
For instance, in the context of media investment:
* **Default Setting:** The baseline value for media investment is 0.
* **Custom Setting:** You can change this baseline to a specific amount that better represents your typical media spend, providing a more accurate measure of the impact on KPIs like sales.
By modifying baseline values, you gain greater flexibility and control over your attribution analyses, enabling you to derive more actionable and business-specific insights from Alvíss AI's powerful data-driven platform.
### Analyzing a Single Attribution [#analyzing-a-single-attribution]
After calculating an attribution, you can delve into the details page for in-depth analysis:
1. **Dashboards:**
* Alviss AI provides various dashboards for each variable group, displaying the impact on KPIs.
2. **Explore Tab:**
* Use the `Explore` tab to visualize the effect of a single variable or compare multiple variables' effects on a single graph. This helps in understanding the contribution of each variable to the overall outcome.
### Working with Attributionsets [#working-with-attributionsets]
To analyze multiple attributions simultaneously, you can group them into an Attributionset:
1. **Creating an Attributionset:**
* Group several attributions based on your analysis needs.
* Once the Attributionset is activated, it becomes visible in the `Effect` dashboard, allowing you to view aggregated impacts.
2. **Handling Overlapping Dates:**
* If chosen attributions with the same Country, Region, and Grouping have overlapping dates, the newer attribution will overwrite the older ones.
3. **Extending an Attributionset:**
* If you want to add new data while maintaining old results for consistency, you can extend an existing Attributionset. This feature is useful for continuous analysis and historical comparison.
### Active Attributionset [#active-attributionset]
Your active Attributionset is the one visualized in the [Effect](../Effect.md) dashboard. To activate the Attributionset press a lighting bolt next to it.
### Ensuring Sensible Results [#ensuring-sensible-results]
To ensure that your attribution results are meaningful and reliable, follow these steps:
1. **Verify Direction of Impact:**
* Check if the effects of your variables on each KPI are in the expected direction (positive or negative).
* For example, if you increase your marketing spend, you would typically expect a positive impact on sales.
2. **Assess Magnitude of Impact:**
* Evaluate whether the size of the effects (magnitude) aligns with your expectations and business understanding.
* For instance, if a minor adjustment in pricing results in an unusually large change in sales, this might indicate a need to review your model or data accuracy.
By following these steps, you can effectively utilize Alviss AI to create, analyze, and manage attributions, gaining valuable insights into the factors driving your business outcomes.
# Attributions
## What is Attribution? [#what-is-attribution]
In Alvíss AI Attribution refers to the process of determining the impact of different business components on outcomes such as sales, customer satisfaction, and marketing effectiveness. This is achieved through a systematic approach that involves running predictions with both baseline and observed values for each variable. By analyzing the differences between these predictions, Alvíss AI provides actionable insights into which factors contribute most to your business outcomes.
## How Attribution Works [#how-attribution-works]
Attribution is calculated through a three-step process:
1. **Baseline Prediction:**
* For each variable we run a prediction using baseline values. These baseline values represent the default or standard levels for the variables under analysis.
* This prediction serves as a reference point, illustrating what the expected outcomes would be without any changes or influences from the observed variables.
2. **Observed Prediction:**
* We run a second set of predictions using the observed values for each variable. These observed values are the actual, real-world data points collected from your business operations.
* This prediction reflects the true impact of the variables based on real data, showing how the outcomes change when influenced by these observed values.
3. **Difference Calculation:**
* The final step involves calculating the difference between the predictions from steps 1 and 2.
* This difference represents the attribution value, highlighting the impact that each variable has on the overall outcome. A positive difference indicates a positive impact, while a negative difference indicates a negative impact.
### Example of Attribution in Action [#example-of-attribution-in-action]
To illustrate how attribution works, let's consider an example where we want to determine the impact of marketing investment on sales:
1. **Baseline Prediction:**
* Marketing Investment (Baseline): \$0
* Predicted Sales (Baseline): 1,000,000 units
2. **Observed Prediction:**
* Marketing Investment (Observed): \$150,000
* Predicted Sales (Observed): 1,200,000 units
3. **Difference Calculation:**
* Attribution Value for Marketing Investment: 1,200,000 (Observed) - 1,000,000 (Baseline) = 200,000 units
In this example, the attribution value of 200,000 units indicates that your investment of \$150,000 in marketing resulted in an increase of 200,000 in sales.
### Using Attribution Results [#using-attribution-results]
Understanding attribution values allows businesses to:
* **Identify Key Drivers:** Determine which variables have the most significant impact on desired outcomes, enabling more focused and effective strategic planning.
* **Optimize Investments:** Allocate resources more efficiently by investing in areas with the highest positive impact.
* **Improve Decision-Making:** Make data-driven decisions by understanding the true effect of different factors on business performance.
### Conclusion [#conclusion]
Attribution in Alvíss AI provides a clear and quantifiable method for assessing the impact of various business components. By comparing baseline and observed predictions, businesses can gain valuable insights into which factors drive success and make informed decisions to optimize their strategies.
# Datasets
# Datasets [#datasets]
## Overview [#overview]
Datasets in Alviss AI are collections that merge selected [uploads](./Uploads) into a unified structure, serving as the foundation for building models, running simulations, predictions, and generating insights. By grouping related data files (e.g., Sales, Media, Brand), Datasets enable consistent analysis and ensure all actions—like training models or creating attributions—are traceable back to the exact data used.
Any platform action (e.g., model fitting, simulation runs) logs the associated Dataset, allowing you to review what a Dataset has been used for. This traceability supports auditing, reproducibility, and collaboration within your [team](../Teams).
We treat Datasets as immutable—any update (e.g., adding new uploads or variables) creates a new Dataset rather than modifying the existing one. This immutability ensures strong traceability, so you always know the precise data behind each action or insight.
To make tracking and usage of uploaded data easier, Alviss AI uses the concept of Datasets. In a Dataset, the chosen uploaded files are grouped together and then used for training models and drawing the insights.
## New Dataset [#new-dataset]
After uploading your data files via [Uploads](./Uploads), create a Dataset to organize and activate them for use. In the Dataset creation flow, you can:
* Select which uploads to include, based on their [data types](./Files/index.md) and compatibility.
* Extend an existing Dataset with additional uploads, which is especially useful for incorporating new data sources or updating with recent observations (this creates a new Dataset per the immutability rule).
* Add external variables, such as macro indicators from [Macro](./Files/Macro) or [Weather](./Files/Weather). Choose the variables of interest, and they will be added to your Dataset automatically.
To create a new Dataset:
1. Navigate to `Data > Datasets` in the side menu.
2. Click `Create New Dataset`.
3. Choose files from your Data Uploads list.
4. Optionally extend an existing Dataset or add external variables.
5. Review and confirm—the platform validates for consistency (e.g., matching [periodicity](./Format/Periodicity)).
It is possible to extend an existing Dataset, which is especially useful when you want to add a new data source or update your data with new observations.
## Active Dataset [#active-dataset]
For a Dataset to serve as the default in your project (e.g., for visualizations or new models), it must be activated. The Active Dataset is automatically used in features like the [Activities](../Activities) dashboard and selected by default for model training, attributions, simulations, and other insights.
To activate a Dataset:
* During creation: Enable the activation option in the flow.
* From the Dataset list: Click the lightning bolt icon next to the desired Dataset.
* From the Dataset details page: Select the activation button.
You can switch the Active Dataset at any time, but only one can be active per project. View the details page for a Dataset to see its usage history, included uploads, variables, and traceability logs.
For more on using Datasets in workflows, see [Models](../Models/Models/index.md), [Simulations](../Simulations), or [Predictions](../Predictions). If validation fails during creation, use the \[File Debugger]\(./Uploads#debugging uploads) on underlying uploads.
# External Data
## Overview [#overview]
To simplify data integration for our users, Alviss AI provides built-in external data sources for weather and macroeconomic factors. These can be automatically added during [Dataset](./Datasets) creation or extension, enriching your models with contextual variables without manual uploads. This feature supports more accurate attributions, simulations, predictions, and optimizations by accounting for environmental and economic influences on your KPIs.
External data is sourced from reliable providers and tailored to your project's [Country](./Format/Country) and [Region](./Format/Region). For multi-country Datasets, indicators are added where available; unavailable countries are skipped without error.
External data respects your project's [Periodicity](./Format/Periodicity), aggregating values (e.g., averages or sums) to match intervals like weekly or monthly.
## Weather [#weather]
Weather data helps model impacts from environmental conditions, such as how precipitation affects foot traffic or temperature influences demand for seasonal products. Sourced from [Meteostat](https://meteostat.net/en/), we sample from weather stations near the country's capital by default. If a valid ISO 3166-2 code is provided in the [Region](./Format/Region) field, sampling shifts to the largest city in that region (based on population) for more localized accuracy.
Supported indicators:
* **Temperature**: The average air temperature in °C.
* **Precipitation**: The daily precipitation total in mm.
* **Wind**: The average wind speed in km/h.
To include weather:
* During Dataset creation, select "Add External Variables" and choose Weather indicators.
* Data is auto-fetched and appended based on your Dataset's geographic scope.
For best results, use ISO-standard [Region](./Format/Region) codes to enable precise, city-level sampling over capital defaults.
## Macro [#macro]
Macroeconomic data captures broader market trends, such as how unemployment affects consumer spending or inflation influences pricing strategies. Sourced from the [OECD](https://www.oecd.org/en.html), availability varies by country—not all indicators are supported everywhere. For Datasets with multiple countries, we add indicators where possible and skip unavailable ones.
Supported indicators:
* **Unemployment Rate**: Percentage of the labor force without work but available and seeking employment (% of labour force).
* **Inflation (CPI)**: Change in consumer prices for a basket of goods and services (Annual Growth Rate %).
* **Long-term Interest Rates**: Rates on government bonds maturing in ten years (% per annum).
* **Short-term Interest Rates**: Rates on three-month money market or government paper (% per annum).
* **Passenger Car Registrations**: Number of new passenger vehicle registrations (Baseline 2015).
* **Business Confidence Index**: Composite indicator of business sentiment (Baseline of 100).
* **Consumer Confidence Index**: Composite indicator of consumer sentiment (Baseline of 100).
* **Composite Leading Indicator**: Aggregated indicators predicting economic cycles (Baseline of 100).
* **COVID Stringency Index**: Measure of government response restrictions, scaled from 0 to 100 (100 = strictest).
To include macro data:
* During Dataset creation or extension, select "Add External Variables" and choose desired indicators.
* Data is fetched and integrated based on your Dataset's countries and time periods.
If an indicator is unavailable for a country in your Dataset, that country will be skipped for that variable—no data gaps are introduced.
For more on incorporating external data into workflows, see [Datasets](./Datasets) or [Models](../Models/Models.md). If you need custom external sources, explore the [API](../API) for integration.
## Updating Variables [#updating-variables]
When extending an existing [Dataset](./Datasets) with new uploads that include additional dates (beyond those in the original Dataset), Alviss AI automatically fetches and appends updated data for any external variables already included. This ensures your Dataset remains comprehensive and up-to-date without manual intervention.
For example:
* If your Dataset includes weather indicators like Temperature or Precipitation, new data points will be retrieved from [Meteostat](https://meteostat.net/en/) to cover the extended time period.
* Similarly, for macroeconomic factors like Unemployment Rate or Inflation (CPI), fresh data from the [OECD](https://www.oecd.org/en.html) will be added where available.
This seamless update maintains data consistency and supports accurate modeling, simulations, and insights over expanded timelines.
\:::note Extensions create a new immutable Dataset version, preserving traceability. See Datasets for details on the extension process. :::
# Interpolation And Extrapolation
When data is uploaded with missing dates or when performing predictions/simulations into the future, Alviss AI automatically handles missing values through interpolation (for gaps within the data) and extrapolation (for extending into the future or past). This ensures consistent and complete datasets for analysis, modeling, and visualization.
The process applies a sequence of filling methods to missing values (represented as NaN or null). Methods are applied in order until all missing values are resolved. The specific sequence depends on the variable type, as different data categories (e.g., sales, media spend) behave differently and require tailored handling to maintain accuracy and realism.
## Key Methods Used [#key-methods-used]
The following methods are employed to fill missing values:
* **Interpolate**: Performs linear interpolation between known values. This is ideal for filling gaps in the middle of a time series but does not handle leading (early) or trailing (late/future) missing values on its own.
* **Forward Fill**: Propagates the last known value forward to fill subsequent missing values. Useful for extending trends into the future (extrapolation) or handling trailing gaps.
* **Backward Fill**: Propagates the next known value backward to fill previous missing values. Useful for handling leading gaps or backfilling from future data points.
* **Set Value**: Sets all remaining missing values to a fixed value (default is 0). This is a fallback method to ensure no NaNs remain, often used for variables where assuming zero makes business sense (e.g., no activity recorded).
For **interpolation** (internal gaps), methods like Interpolate are prioritized where appropriate. For **extrapolation** (e.g., future predictions or simulations), Forward Fill or Set Value are commonly used to extend data logically. The system processes data along the time axis, assuming dates are in chronological order.
## Rules by Variable Group [#rules-by-variable-group]
Each variable group has a predefined sequence of methods. These are applied in the listed order. If a method doesn't fully resolve the missing values, the next one is tried.
* **Sales**:
* Set Value (to 0)
* **Media Conversion Factor**:
* Interpolate
* Backward Fill
* Forward Fill
* Set Value (to 0)
* **Price**:
* Interpolate
* Forward Fill
* Backward Fill
* **Profit**:
* Interpolate
* Forward Fill
* Backward Fill
* **Cost**:
* Interpolate
* Forward Fill
* Backward Fill
* **Competitor Price**:
* Interpolate
* Forward Fill
* Backward Fill
* **Distribution**:
* Interpolate
* Forward Fill
* Backward Fill
* Set Value (to 0)
* **Competitor Distribution**:
* Interpolate
* Forward Fill
* Backward Fill
* Set Value (to 0)
* **Visits**:
* Interpolate
* Forward Fill
* Backward Fill
* Set Value (to 0)
* **Brand**:
* Interpolate
* Forward Fill
* Backward Fill
* Set Value (to 0)
* **Competitor Brand**:
* Interpolate
* Forward Fill
* Backward Fill
* Set Value (to 0)
* **Weather**:
* Interpolate
* Forward Fill
* Backward Fill
* Set Value (to 0)
* **Extra (Custom Variables)**:
* Interpolate
* Forward Fill
* Backward Fill
* Set Value (to 0)
* **Macro (Economic Indicators)**:
* Interpolate
* Forward Fill
* Backward Fill
* Set Value (to 0)
* **Media**:
* Set Value (to 0)
* **Customer Experience**:
* Set Value (to 0)
* **Competitor Media**:
* Set Value (to 0)
## Notes [#notes]
* These rules are designed to balance accuracy, computational efficiency, and business logic. For example, media-related variables default to 0 for missing data, assuming no spend or activity.
* If your data requires custom handling beyond these defaults, consider preprocessing it before upload or consulting with a data specialist.
* Always inspect your data in the Activities dashboard after upload to verify that interpolations and extrapolations align with expectations, especially before building models.
# Uploads
## Overview [#overview]
The Uploads section in Alviss AI serves as the central hub for managing all data files you've imported into your project. Accessible via the side menu under `Data > Uploads`, this page provides a comprehensive view of your uploaded files, allowing you to track metadata, inspect contents, and integrate them into datasets. Each upload corresponds to one of the supported [data types](./Files/index.md) (e.g., Sales, Media), and once validated, it becomes available for creating or extending [Datasets](./Datasets).
From here, you can review upload details, add notes for context, and dive deeper into data exploration. This ensures transparency and ease of collaboration within your [team](../Teams).
## Upload List [#upload-list]
Navigate to `Data > Uploads` to view a list of all files uploaded to the current project. For each upload, the following information is displayed:
* **Creator:** The team member who uploaded the file.
* **Upload Timestamp:** The date and time the file was uploaded.
* **Data Type:** The category of the data, linking to the relevant [Files](./Files/index.md) documentation (e.g., Sales, Brand).
* **Modeling Combinations:** Available combinations of factors like Country, Region, and Grouping, as defined in [Modeling Combination](../Models/Modeling%20Combination). This shows the scope of data coverage for modeling.
* **Associated Datasets:** Which [Datasets](./Datasets) include this upload, helping track usage across your workflow.
* **Variables:** A summary of the key variables or columns present in the upload, useful for quick reference before building models.
Additionally:
* **Add Notes:** Attach custom notes to any upload for extra details, such as data sources, assumptions, or preprocessing notes. This aids team collaboration and documentation.
* **Data Exploration:** Open a specific variable or the entire upload in the Data Explorer for interactive visualization and inspection.
Use the search and filter options on the Upload List to quickly locate files by type, uploader, or date. This is especially helpful in larger projects with multiple uploads.
## New Upload [#new-upload]
To add new data files to your project:
1. Navigate to the Upload List by selecting `Data > Uploads` in the side menu, then click `Upload New Data` in the upper right corner.
2. Optionally, set a custom `Name` prefix. This will be applied to all files in the upload batch for easy identification (e.g., "Q3\_2025\_Sales\_Data\_").
3. Drag and drop files or click to select them in the designated area for the desired [data type](../Data/Files/index.md) (e.g., drop a sales CSV into the Sales section).
4. Repeat step 3 for as many files and types as needed in this batch.
5. Proceed by either:
* Following the guided Dataset creation flow to immediately create or extend a [Dataset](./Datasets) with the new uploads.
* Navigating back to `Data > Uploads` to review the processed files in the list.
Files undergo automatic validation during upload (see \[File Format]\(Format/File Format.md) for requirements). Successful uploads appear in the list; failures trigger notifications with details.
Ensure files match the required \[format]\(Format/File Format.md) and [periodicity](./Format/Periodicity) of your project to avoid validation issues. See [Files](./Files/index.md) for how the different files are supposed to be structured. See \[File Format]\(./Format/File Format.md) for exact details on supported file formats, but a quick summary is:
## Supported Formats [#supported-formats]
* **CSV (Comma-Separated Values):** Plain text files with comma-separated fields.
Excel may default to semicolons (;) or tabs in some regions—explicitly select comma when saving as CSV.
* **Excel:** .xlsx (standard Excel format).
In Excel, dates may auto-format based on your locale (e.g., MM/DD/YYYY vs. DD/MM/YYYY). Always export as text or force ISO 8601 (YYYY-MM-DD) to avoid corruption.
## Debugging Uploads [#debugging-uploads]
If a file fails validation (e.g., due to formatting errors or mismatched data types), use the built-in File Debugger to diagnose and resolve issues. This tool provides detailed error breakdowns, highlighting problematic rows, columns, or values.
To access the File Debugger:
* From a failed upload in the Upload List, click "Open in File Debugger."
* Alternatively, from the Upload page, select the "File Debugger" tab, upload the problematic file, and choose its [data type](./Files/index.md).
The debugger scans the file and returns:
* Error messages with line/column references.
* Suggestions for fixes (e.g., correct decimal separators or date formats).
* A preview of the data for quick inspection.
* On the right side, one can click on the error and it will go to the relevant error in the file (highlighted in red).
* In the file debugger, one can edit the file "live" and upload it when it passes all the checks.
When all errors are resolved, one can either export the corrected file or upload it directly from the debugger.
Common pitfalls include locale-based formatting in Excel (e.g., dates or separators). Always validate against [File Format](./Format/File%20Format.md) guidelines before uploading.
# Data
The Alvíss AI application has a set of strict requirements on the types of data it can work with. This section will run you through the file formats, conventions, and assumptions that
this application is operating under. The application supports models, data, and insights on a granular level.
* Alvíss AI is a flexible platform that allows you to add various data sources you need for your specific business.
* We support Sales, Price, Media, Customer Experience, Brand, Visits, Events, Macro, Competitor, and Weather data out of the box.
* Each of these data sources needs to adhere to a specification in order for the platform to understand them.
* While it’s possible and recommended to add all the data sources you can get your hands on, the only requirement is “Sales”. This means you can start out simple and move to a more complex setup later.
## Data explanation [#data-explanation]
Alvíss AI needs a number of data sources to function properly. The main
data sources supported are:
* [Sales](./Files/Sales.md): Core dataset tracking units sold, price per unit, and optionally profit per unit to model business outcomes like revenue and demand.
* [Brand](./Files/Brand.md): Metrics on your brand's market perception, such as awareness, liking, penetration, and customer experience tracking.
* [Competitor Brand](./Files/Competitor%20Brand.md): Similar perception metrics for competitors' brands to analyze market dynamics and competitive effects.
* [Distribution](./Files/Distribution.md): Metrics on your distribution network, like number of stores, sales agents, or offices, to model operational presence.
* [Competitor Distribution](./Files/Competitor%20Distribution.md): Distribution metrics for competitors to understand their market reach and impact on your performance.
* [Media](./Files/Media.md): Investments and metrics (e.g., impressions, clicks) for your advertising campaigns across channels like display or Google.
* [Competitor Media](./Files/Competitor%20Media.md): Media investments by competitors to model competitive advertising pressure.
* [Competitor Price](./Files/Competitor%20Price.md): Pricing data for competitors' products to assess price elasticity and market competition.
* [Customer Experience](./Files/Customer%20Experience.md): Investments in CX improvements (e.g., IT, human resources) to estimate ROI on customer satisfaction efforts.
* [Events](./Files/Events.md): Time-bound occurrences like outages or strikes to account for disruptions in modeling.
* [Extra](./Files/Extra.md): Custom variables that don't fit other categories, for flexible inclusion of unique business metrics.
* [Macro](./Files/Macro.md): Macroeconomic indicators like unemployment or consumer confidence to capture broader economic influences.
* [Visits](./Files/Visits.md): Traffic metrics to websites or stores from channels like direct or paid search, to link engagement to conversions.
* [Weather](./Files/Weather.md): Meteorological data like precipitation or wind to model environmental impacts on weather-sensitive operations.
```
These data sources have a specific [File Format](./Format/File Format.md) that needs to be adhered to in order for the application to understand them.
```
```
The data sources need to have a coherent data [Periodicity](./Format/Periodicity.md) meaning that the values need to be observed and registered in the same interval.
```
# Active Model
In Alviss AI, an **active model** refers to the model that is designated as the default for a specific combination of Country, Region, and Grouping (e.g., "US - West Coast - E-commerce"). This setup ensures that when you run analyses, simulations, predictions, or view dashboards like [Effect](../Effect.md), the platform automatically uses the active model for that particular combination, streamlining your workflow and reducing the need to manually select models each time.
Activating a model is a simple process that optimizes performance and accessibility:
* It makes the model readily available for generating insights without additional setup.
* Only one model can be active per unique combination at a time; activating a new one will deactivate the previous.
* This feature is especially useful in team environments, where shared projects benefit from consistent defaults across members.
* Lower user roles can only use the default model.
#### How to Activate a Model [#how-to-activate-a-model]
1. **Navigate to Models:** Go to the Models section in your project via the side menu.
2. **Select a Model:** From the list of trained models, choose the one you want to activate.
3. **Activate:** Click the activation option (small button with a lightning bolt). This sets it as the default for its associated combination.
4. **Optional Automation:** During model building in the \[Basic Model Builder]\(Basic Model Builder.md) or \[Advanced Model Builder]\(Advanced Model Builder), you can enable an option to automatically activate the model upon successful training.
#### Benefits of Using Active Models [#benefits-of-using-active-models]
* **Efficiency:** Speeds up insight generation, such as running [Attributions](../Attributions/index.md), [Simulations](../Simulations), or [Predictions](../Predictions), by eliminating repetitive selections.
* **Consistency:** Ensures all team members in a shared project use the same model for a given combination, promoting aligned decision-making.
* **Flexibility:** You can switch active models as needed, for example, when testing new versions or updating based on fresh data.
Before activating, review the model's performance metrics (e.g., accuracy on hold-out data) to ensure it's the best fit. If you're working with multiple combinations, activate models strategically to cover your key analytical needs.
If your project involves complex setups or you encounter issues with activation, refer to the [Models](../Models/Models/index.md) documentation for more details or check your project's settings.
# Basic Model Builder
The Basic Model Builder is ideal for users seeking a quick and efficient way to create models with minimal configuration. It leverages sensible defaults to automate much of the process, allowing you to focus on high-level decisions while the platform handles the underlying complexities. To get started, simply click the **New Model** button, make a few adjustments, and let Alviss AI build the model automatically.
This builder is particularly useful for initial explorations or when you need rapid insights into how various drivers (e.g., marketing, pricing, or seasonal trends) impact your key performance indicators (KPIs), such as sales or churn.
#### Steps to Build a Model [#steps-to-build-a-model]
1. **Select Dataset**\
Choose the [Dataset](../Data/Datasets) that will serve as the foundation for your model. This dataset provides the raw data for analysis, including variables like sales figures, marketing spend, or external factors. Ensure the selected dataset aligns with your project's [periodicity](../Data/Format/Periodicity) and has been validated for quality.
2. **Choose Modeling Combination**\
Specify the \[modeling combinations]\(Modeling Combination.md) based on dimensions such as country, region, or grouping. For each unique combination (e.g., "US - East Coast - Retail"), Alviss AI will build a dedicated model. This allows for granular, tailored insights while maintaining scalability across your data.
3. **Set Effects**\
Define the variable groups to include in the model, drawn from your dataset. Common groups include Media (e.g., ad spend), Season (e.g., holiday effects), Trend (e.g., long-term market shifts), Pricing, and more.
* Optionally, indicate the expected directional impact of each group on your target KPI (e.g., positive for marketing investments increasing sales).
* Note: Including more groups enhances model comprehensiveness but may increase training time due to added complexity.
4. **Select a Date Range**\
Define the time periods for model training:
* **Training Period:** The historical data range used to fit the model.
* **Hold-Out Period:** A separate range reserved for validation, helping assess the model's predictive accuracy on unseen data.
5. **Advanced Settings (Optional)**\
Customize technical parameters for finer control:
* Adjust the number of samples, learning rate, and epochs to influence training efficiency and model convergence.
* Enable post-training actions, such as generating [Predizctions](../Predictions), [Attributions](../Attributions/index.md), or comparing Prior vs. Posterior distributions for deeper insights.
* Opt to automatically \[activate the model]\(Active Model.md) upon completion, making it immediately available for use in dashboards like [Effect](../Effect) or [Activities](../Activities).
For best results, start with default settings and iterate based on initial outputs. If you require more customization (e.g., custom priors or complex variable interactions), consider switching to the \[Advanced Model Builder]\(Advanced Model Builder).
Once submitted, Alviss AI will train the model in the background. You'll receive notifications upon completion, and the model will appear in your project's model list for review, activation, or further refinement.
# Modeling Combination
In Alviss AI, modeling combinations provide a flexible way to structure your machine learning models around key business dimensions, ensuring granular and targeted insights. Each model is designed to cover a single unique combination of **[Country](../Data/Format/Country)**, **[Region](../Data/Format/Region)**, and **[Grouping](../Data/Format/Grouping)**, allowing you to analyze data at the level that best suits your needs—whether that's a broad overview or detailed, localized breakdowns.
This approach aligns with Alviss AI's focus on holistic business measurement and optimization, where models quantify the impact of drivers like marketing, pricing, and external factors on KPIs such as sales, churn, or demand.
* **Dimensions Explained:**
* **[Country](../Data/Format/Country):** Represents the national or geographic market (e.g., "US", "Germany"). Use this to isolate country-specific trends, regulations, or consumer behaviors.
* **[Region](../Data/Format/Region):** A sub-division within a country (e.g., "West Coast", "Bavaria"). This adds finer granularity for regional variations in performance.
* **[Grouping](../Data/Format/Grouping):** Custom categories like product lines, customer segments, or channels (e.g., "Retail", "E-commerce"). This allows tailoring models to specific business units or strategies.
* **One Model Per Combination:**\
A single model is built and trained for each unique combination of these dimensions (e.g., "US - West Coast - Retail"). This ensures the model captures interactions specific to that slice of data, avoiding overgeneralization while enabling scalable analysis across your [project](../Projects.md).
Leverage [filtering](../Filtering) in dashboards to dynamically view results across multiple combinations without rebuilding models.
Modeling combinations cannot be changed after model training. If your data evolves (e.g., new regions added), extend your [dataset](../Data/Datasets) and refit models as needed.
For more on building models around combinations, see [Models](./index.md). If you need advanced customization, explore the [API](../API) for programmatic management.
# Prior vs Posterior
## Overview [#overview]
Prior vs Posterior shows how each variable's effect distribution changes after model fitting. By comparing the assumed priors with the learned posteriors, you can assess whether the model has enough data to update its beliefs and whether the fitted effects align with domain expectations.
## Visualizations [#visualizations]
Toggle between two plot types using the radio buttons in the header:
* **Box** — box plots showing the distribution spread (median, quartiles, outliers).
* **Density** — smoothed density curves for a more detailed shape comparison.
Plots are organized into tabs by variable group (Media, Price, Distribution, Holiday, Season, Trend, etc.).
## Transformations [#transformations]
The **Transformation** selector controls what is shown on the X axis:
| Transformation | Description |
| ---------------- | --------------------------------------------------------------------- |
| **Effect** | The raw impact the variable has on the target |
| **Impact Ratio** | Effect normalized by the target sum: `effect / sum(abs(target))` |
| **Mean** | Mean effect per epoch |
| **Return** | Effect normalized by the variable size: `effect / sum(abs(variable))` |
## Filtering [#filtering]
Click **Filters** to narrow results by:
* **Variables** — select specific variables
* **Groups** — select variable groups
* **Targets** — select target variables
## When to Use [#when-to-use]
* **Model validation** — if posteriors barely shift from priors, the model may lack sufficient data for that variable.
* **Sanity checking** — verify that effect directions match business intuition (e.g., media spend should have a positive effect).
* **Comparing models** — run prior vs posterior on different model versions to see how parameter estimates evolve.
## See Also [#see-also]
* [Models](../Models) — build and manage models
* [Attributions](../Attributions) — understand variable contributions in detail
# Models
In this section, you can create and customize AI models to then drive insights, run [Simulations](../Simulations.md), make [Predictions](../Predictions.md), or calculate [Attributions](../Attributions/index.md). Depending on your needs and level of expertise, you have two options for building models:
* **\[Basic Model Builder]\(Basic Model Builder.md):** Ideal for users seeking a straightforward approach, the Basic Model Builder provides sensible defaults and an easy-to-use interface. This tool allows you to create a functional model quickly, without requiring extensive domain knowledge.
* **\[Advanced Model Builder]\(Advanced Model Builder):** For those who need to capture specific dynamics or customize the model to address unique business scenarios, the Advanced Model Builder offers greater flexibility. This tool allows you to fine-tune your model to incorporate detailed variables and complex interactions.
Select the model-building approach that best fits your requirements and expertise to effectively leverage Alviss AI’s capabilities for in-depth analysis and decision-making.
### Modelling Combination [#modelling-combination]
One model can cover one combination of Country, Region, and Grouping.
# Permissions And Roles
In Alviss AI, roles define the level of access and functionality available to users within a team. These roles help streamline workflows, ensure data security, and promote efficient collaboration by granting appropriate permissions based on user responsibilities. As of August 26, 2025, the following roles are available, each tailored to different user needs.
### Observer [#observer]
**Access Level**: Basic\
**Permissions**:
* View all dashboards to monitor project progress and insights.
**Who It's For**:\
Team members who need to stay informed about key metrics and outcomes without modifying data or models, such as stakeholders or analysts in a monitoring capacity.
### Member [#member]
**Access Level**: Intermediate\
**Permissions**:
* View all dashboards.
* Run simulations, predictions, and optimizations to explore scenarios.
**Who It's For**:\
Users who actively analyze data and test strategies but do not manage underlying data or models, such as planners or forecasters.
### Data Manager [#data-manager]
**Access Level**: Advanced\
**Permissions**:
* All Member permissions.
* Upload, update, and manage data files and datasets.
**Who It's For**:\
Individuals responsible for data integrity and preparation, such as data engineers or coordinators ensuring accurate inputs for analysis.
### Model Developer [#model-developer]
**Access Level**: Expert\
**Permissions**:
* All Data Manager permissions.
* Build, train, and refine AI models.
* Create attributions to evaluate model impacts.
**Who It's For**:\
Data scientists or AI specialists focused on developing and iterating models to drive analytical capabilities.
### Manager [#manager]
**Access Level**: Leadership\
**Permissions**:
* All Model Developer permissions.
* Activate models to set them as project defaults.
* Update project settings, including default models and datasets.
* Configure dashboards like Activities and Effects.
**Who It's For**:\
Team leads or project owners overseeing strategy, model deployment, and overall decision-making.
### Admin [#admin]
**Access Level**: Full Control\
**Permissions**:
* All Manager permissions.
* Manage users: add, remove, and assign roles within the team.
**Who It's For**:\
Top-level administrators or organization leaders handling team structure, access control, and platform governance.
## Choosing the Right Role [#choosing-the-right-role]
Assign roles based on each team member's responsibilities to balance access and security. Start with the least privilege needed and adjust as projects evolve. This approach minimizes risks while maximizing productivity. If roles change frequently, consider periodic reviews to align with team dynamics.
## Permissions Table [#permissions-table]
A user's role determines their permissions on a project. The table below outlines access for key actions:
| **Action** | **Observer** | **Member** | **Data Manager** | **Model Developer** | **Manager** | **Admin** |
| -------------------------------------------- | ------------ | ---------- | ---------------- | ------------------- | ----------- | --------- |
| [Access Activities Dashboard](../Activities) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Access Effects Dashboard](../Effect) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Predictions](../Predictions) | | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Simulations](../Simulations) | | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Optimizations](../Optimizations) | | ✓ | ✓ | ✓ | ✓ | ✓ |
| [Files](../Data/Files/index.md) | | | ✓ | ✓ | ✓ | ✓ |
| [Create Datasets](../Data/Datasets) | | | ✓ | ✓ | ✓ | ✓ |
| Data Explorer | | | ✓ | ✓ | ✓ | ✓ |
| [Response Curves](../Response%20Curves) | | | ✓ | ✓ | ✓ | ✓ |
| [Models](../Models/Models.md) | | | | ✓ | ✓ | ✓ |
| Create Attributions | | | | ✓ | ✓ | ✓ |
| Activate Models | | | | | ✓ | ✓ |
| Update Activities Dashboard | | | | | ✓ | ✓ |
| Update Effects Dashboard | | | | | ✓ | ✓ |
| Configure Project | | | | | ✓ | ✓ |
| Add User | | | | | | ✓ |
| Remove User | | | | | | ✓ |
| Change User Roles | | | | | | ✓ |
This permissions structure promotes secure and efficient team operations. For role assignments, Admins can manage via the team settings page. If you need custom configurations or have questions, contact support.
# Users
You can easily manage your user account by clicking on your profile picture in the top-right corner of the Alviss AI platform and selecting **Your Account**. This opens your account details page, where you can update personal information, manage security settings, and handle team memberships.
## Account Details [#account-details]
On the account details page, view key information such as your username, email address, and associated teams. This section provides a quick overview of your profile and serves as the starting point for further customizations.
## Change Password [#change-password]
To update your password:
1. Navigate to the **Change Password** section on the account details page.
2. Enter your current password and your new password (following security guidelines, such as minimum length and complexity).
3. Confirm the change.
Regularly updating your password enhances account security. If you forget your password, use the recovery options on the login page.
## Delete Account [#delete-account]
If you need to permanently delete your account:
1. Go to the **Delete Account** section.
2. Confirm the action after reviewing the warning—this step is irreversible.
Deleting your account removes all associated data, models, datasets, and access to the platform. We recommend exporting any important information (e.g., via [Datasets](../Data/Datasets.md) or reports) beforehand.
## Leave Team [#leave-team]
On the **Teams** tab, you'll see a list of all teams you're part of. To leave a team:
1. Select the team from the list.
2. Click **Leave Team** and confirm.
Leaving a team revokes your access to its projects, datasets, and models. If you're the last admin, consider transferring ownership first to avoid data loss.
## Edit Avatar [#edit-avatar]
Customize your profile by adding or changing your avatar:
1. In the account details page, click on your current avatar or the upload area.
2. Select an image file (supported formats: JPEG, PNG; recommended size: 512x512 pixels).
3. Crop and confirm the upload.
Your avatar appears in the platform interface, team lists, and activity logs for easy identification.
## Edit Username [#edit-username]
To change your username:
1. Go to the **Edit Username** section.
2. Enter a new unique username (alphanumeric characters, underscores allowed; 3-20 characters).
3. Save the changes.
Usernames are visible to your team and used in logs. Choose one that's professional and memorable.
## Managing Access Tokens [#managing-access-tokens]
Access tokens enable secure API integrations with Alviss AI (see [API](../API) for details). Manage them at [https://app.alviss.io/-/user#access-tokens](https://app.alviss.io/-/user#access-tokens) or via **Your Account > Access Tokens**.
### Create Access Token [#create-access-token]
1. Click **Create New Token**.
2. In the modal:
* **Name**: Provide a descriptive name (e.g., "API Integration Token").
* **Expires At**: Set an expiration date (up to 365 days; we recommend short durations for security).
3. Submit—the token displays once. Copy and store it securely, as it won't be retrievable later.
### Revoke Access Token [#revoke-access-token]
To invalidate a token:
1. Locate it in the list.
2. Click **Revoke** and confirm.
Revocation is immediate and permanent, useful for compromised tokens or completed tasks.
For best practices, limit token scopes and durations. If you encounter issues, contact support.
# Brand
Brand data captures metrics about your brand's perception and performance in the market, such as awareness, liking, penetration, consideration, and recommendation. This category also includes customer experience-related tracking (e.g., satisfaction scores or Net Promoter Score).
These metrics are often sourced from third-party providers like [YouGov](https://yougov.co.uk/). Alviss AI uses this data to estimate your brand's contribution to overall sales and other KPIs. By incorporating brand tracking, you can quantify how brand strength influences business outcomes.
## Data Requirements [#data-requirements]
The Brand Data file must include the following columns (headers). All columns are required unless marked as optional:
* **[Country](../Format/Country)** (string, required): A three-letter country code per ISO 3166 standard (e.g., "SWE" for Sweden), indicating where the metrics were collected.
* **[Region](../Format/Region)** (string, optional, defaults to "all"): The region within the country (e.g., "all" for nationwide or a specific ISO 3166-2 code like "SE-AB" for Stockholm County in Sweden).
* **[Grouping](../Format/Grouping)** (string, optional, defaults to "all"): For additional segmentation, such as product categories, demographics, or sales territories.
* **[Date](../Format/Date)** (date, required): The collection date in ISO 8601 format (YYYY-MM-DD).
* **Brand** (string, optional, defaults to "all"): The brand name or identifier (e.g., "AwesomeInsurance").
* **Metric** (string, required): The metric type (e.g., "Unaided Awareness", "Aided Awareness", "Consideration", "Likeability", "Penetration", "Recommendation").
* **Value** (float, required): The metric value (e.g., a percentage like 64.74).
Only the following characters are allowed when enter text values: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
## Supported Formats [#supported-formats]
Data can be uploaded in **long** (tidy) or **wide** (pivoted) format. Choose based on your data pipeline:
* **Long Format** (Recommended for flexibility): Each row represents a single observation (one metric per brand, date, etc.).
| Country | Region | Grouping | Date | Brand | Metric | Value |
| ------- | ------ | -------- | ---------- | ---------------- | ----------------- | ----- |
| SWE | all | all | 2018-01-07 | AwesomeInsurance | Unaided Awareness | 64.74 |
| SWE | all | all | 2018-01-07 | CoolInsurance | Unaided Awareness | 62.17 |
| SWE | all | all | 2018-01-07 | AwesomeInsurance | Aided Awareness | 70.44 |
| SWE | all | all | 2018-01-07 | CoolInsurance | Aided Awareness | 79.77 |
| SWE | all | all | 2018-01-07 | AwesomeInsurance | Consideration | 26.16 |
| SWE | all | all | 2018-01-07 | BestInsurance | Consideration | 30.74 |
* **Wide Format** (Useful for spreadsheets): Columns represent combinations of Brand and Metric, with rows as dates. The first few rows define fixed metadata (e.g., Country, Region, Brand, ..), .
| Country | SWE | SWE | SWE | SWE | SWE | SWE |
| ---------- | ----------------- | ----------------- | ---------------- | --------------- | ---------------- | ------------- |
| Region | all | all | all | all | all | all |
| Brand | AwesomeInsurance | CoolInsurance | AwesomeInsurance | CoolInsurance | AwesomeInsurance | CoolInsurance |
| Metric | Unaided Awareness | Unaided Awareness | Aided Awareness | Aided Awareness | Consideration | Consideration |
| Grouping | all | all | all | all | all | all |
| 2018-01-08 | 64.74 | 62.17 | 70.44 | 79.77 | 26.16 | 32.77 |
| 2018-01-15 | 55.33 | 60.97 | 82.22 | 92.25 | 30.77 | 32.08 |
| 2018-01-22 | 62.93 | 55.16 | 89.15 | 77.46 | 26.79 | 27.84 |
| 2018-01-29 | 64.32 | 52.21 | 79.02 | 70.13 | 30.59 | 27.09 |
| 2018-02-05 | 63.7 | 54.71 | 81.49 | 78.1 | 30.3 | 33.25 |
| 2018-02-12 | 52.86 | 61.27 | 71.73 | 73.5 | 30.52 | 30.97 |
| 2018-02-19 | 64.08 | 65.53 | 83.72 | 74.47 | 27.71 | 26.84 |
## Best Practices [#best-practices]
* **Consistency:** Ensure dates align with your project's periodicity (e.g., weekly data if the project is set to weekly granularity). Mismatched granularity will cause upload errors.
* **Data Quality:** Check for outliers, missing values, or inconsistencies before upload. Use the [Activities](../../Activities) dashboard to visualize and validate post-upload.
* **Granularity Alignment:** All data in a project must match the chosen periodicity (set during project creation). For details, see [Projects](../../Projects).
* **Multiple Brands:** If tracking competitors, include them with clear identifiers to enable comparative analysis.
# Competitor Brand
Competitor brand data captures metrics about your competitors' brands in the market, such as awareness, liking, penetration, consideration, and recommendation. These metrics help quantify how competitors' brand strength influences market dynamics, customer preferences, and your own business performance.
Similar to your own brand data, these metrics are often sourced from third-party providers like [YouGov](https://yougov.co.uk/). Alviss AI uses this data to model competitive effects on your sales, KPIs, and market share. By including competitor tracking, you can perform comparative analyses, identify threats or opportunities, and refine strategies accordingly.
## Data Requirements [#data-requirements]
The Competitor Brand Data file must include the following columns (headers). All columns are required unless marked as optional:
* **[Country](../Format/Country)** (string, required): A three-letter country code per ISO 3166 standard (e.g., "SWE" for Sweden), indicating where the metrics were collected.
* **[Region](../Format/Region)** (string, optional, defaults to "all"): The region within the country (e.g., "all" for nationwide or a specific ISO 3166-2 code like "SE-AB" for Stockholm County in Sweden).
* **[Grouping](../Format/Grouping)** (string, optional, defaults to "all"): For additional segmentation, such as product categories, demographics, or sales territories.
* **[Date](../Format/Date)** (date, required): The collection date in ISO 8601 format (YYYY-MM-DD).
* **Competitor** (string, required): The name or identifier of the competitor company (e.g., "Competitor1").
* **Brand** (string, optional, defaults to "all"): The specific brand name or identifier associated with the competitor (e.g., "AwesomeInsurance"). Use this if competitors have multiple brands; defaults to "all" otherwise.
* **Metric** (string, required): The metric type (e.g., "Unaided Awareness", "Aided Awareness", "Consideration", "Likeability", "Penetration", "Recommendation").
* **Value** (float, required): The metric value (e.g., a percentage like 87.65). Use consistent units (e.g., percentages as decimals or whole numbers; specify in your metadata if needed). Handle missing values with `NaN` or leave blank—Alviss AI will flag inconsistencies during upload.
Only the following characters are allowed when enter text values: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
## Supported Formats [#supported-formats]
Data can be uploaded in **long** (tidy) or **wide** (pivoted) format. Choose based on your data pipeline:
* **Long Format** (Recommended for flexibility): Each row represents a single observation (one metric per competitor, brand, date, etc.).
| Country | Region | Grouping | Date | Competitor | Brand | Metric | Value |
| ------- | ------ | -------- | ---------- | ----------- | ---------------- | ----------------- | ------------------ |
| SWE | all | all | 2018-01-08 | Competitor1 | AwesomeInsurance | Unaided Awareness | 87.65397476360124 |
| SWE | all | all | 2018-01-08 | Competitor1 | CoolInsurance | Unaided Awareness | 35.860897908707926 |
| SWE | all | all | 2018-01-08 | Competitor1 | AwesomeInsurance | Aided Awareness | 95.80406667004866 |
| SWE | all | all | 2018-01-08 | Competitor1 | CoolInsurance | Aided Awareness | 46.7856756466731 |
| SWE | all | all | 2018-01-08 | Competitor1 | AwesomeInsurance | Consideration | 59.883367317492954 |
| SWE | all | all | 2018-01-08 | Competitor1 | BestInsurance | Consideration | 17.325031539537704 |
| SWE | all | all | 2018-01-08 | Competitor1 | CoolInsurance | Consideration | 27.449598901467187 |
* **Wide Format** (Useful for spreadsheets): Columns represent combinations of Brand and Metric, with rows as dates. The first few rows define fixed attributes (e.g., Country, Region, Competitor).
| Country | SWE | SWE | SWE | SWE | SWE | SWE |
| ---------- | ----------------- | ----------------- | ---------------- | ---------------- | ---------------- | ---------------- |
| Region | all | all | all | all | all | all |
| Brand | AwesomeInsurance | CoolInsurance | AwesomeInsurance | CoolInsurance | AwesomeInsurance | BestInsurance |
| Metric | Unaided Awareness | Unaided Awareness | Aided Awareness | Aided Awareness | Consideration | Consideration |
| Grouping | all | all | all | all | all | all |
| Competitor | Competitor1 | Competitor1 | Competitor1 | Competitor1 | Competitor1 | Competitor1 |
| 2018-01-08 | 87.6539747636012 | 35.8608979087079 | 95.8040666700487 | 46.7856756466731 | 59.883367317493 | 17.3250315395377 |
| 2018-01-15 | 92.6168025720957 | 56.7633898031061 | 2.65673292377081 | 96.7171028219704 | 88.5898314242487 | 84.2775120211196 |
| 2018-01-22 | 63.5991809805342 | 53.402872105366 | 96.9545473085919 | 54.7469630755428 | 44.2074333356145 | 56.7240464275083 |
| 2018-01-29 | 56.3267856324564 | 65.3824826953493 | 62.39091267603 | 60.9973615338258 | 21.4336959074193 | 57.3351223750182 |
| 2018-02-05 | 64.6931773096164 | 61.1832960347049 | 70.0994435959415 | 66.9064895385894 | 59.5134005595969 | 89.184757233672 |
## Best Practices [#best-practices]
* **Consistency:** Ensure dates align with your project's periodicity (e.g., weekly data if the project is set to weekly granularity). Mismatched granularity will cause upload errors.
* **Data Quality:** Check for outliers, missing values, or inconsistencies before upload. Use the [Activities](../../Activities) dashboard to visualize and validate post-upload.
* **Granularity Alignment:** All data in a project must match the chosen periodicity (set during project creation). For details, see [Projects](../../Projects).
* **Competitor Tracking:** Include multiple competitors for robust analysis. Use clear, consistent naming for Competitor and Brand fields to enable easy filtering and comparison.
For uploading instructions, see [Upload Data](../Uploads). If you encounter issues, contact support or refer to the [API](../../API) for programmatic uploads.
# Competitor Distribution
Competitor distribution data tracks metrics related to your competitors' physical or operational presence in the market, such as the number of stores, sales agents, offices, or other distribution points. This information is essential for understanding competitive landscapes and how rivals' distribution strategies impact your own sales, market share, and KPIs.
Sourced from market research, public reports, or third-party providers, this data allows Alviss AI to model competitive effects in attributions, simulations, and predictions. For instance, it can quantify how an increase in a competitor's store count affects your demand or pricing strategies, enabling more accurate optimizations and strategic planning.
## Data Requirements [#data-requirements]
The Competitor Distribution Data file must include the following columns (headers). All columns are required unless marked as optional:
* **[Country](../Format/Country)** (string, required): A three-letter country code per ISO 3166 standard (e.g., "SWE" for Sweden), indicating where the distribution metrics apply.
* **[Region](../Format/Region)** (string, optional, defaults to "all"): The region within the country (e.g., "all" for nationwide or a specific ISO 3166-2 code like "SE-AB" for Stockholm County in Sweden).
* **[Grouping](../Format/Grouping)** (string, optional, defaults to "all"): For additional segmentation, such as product categories, demographics, or sales territories.
* **[Date](../Format/Date)** (date, required): The start date of the period for the distribution metrics in ISO 8601 format (YYYY-MM-DD).
* **Competitor** (string, required): The name or identifier of the competitor company (e.g., "Competitor1").
* **Product** (string, optional, defaults to "all"): The name or identifier of the product associated with the distribution (e.g., "Health").
* **Channel** (string, required): The distribution channel (e.g., "Agents", "Stores", "Offices").
* **Value** (integer, required): The count of distribution units (e.g., 90). Use whole numbers; handle missing values with blanks or zeros—Alviss AI will flag inconsistencies during upload.
Only the following characters are allowed when enter text values: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
## Supported Formats [#supported-formats]
Data can be uploaded in **long** (tidy) or **wide** (pivoted) format. Choose based on your data pipeline:
* **Long Format** (Recommended for flexibility): Each row represents a single observation (one value per competitor, product, channel, date, etc.).
| Country | Region | Grouping | Date | Product | Competitor | Channel | Value |
| ------- | ------ | -------- | ---------- | ------- | ----------- | ------- | ----- |
| SWE | all | all | 2018-01-08 | Health | Competitor1 | Agents | 90 |
| SWE | all | all | 2018-01-08 | Life | Competitor1 | Agents | 90 |
| SWE | all | all | 2018-01-08 | Pc | Competitor1 | Agents | 90 |
| SWE | all | all | 2018-01-15 | Health | Competitor1 | Agents | 90 |
| SWE | all | all | 2018-01-15 | Life | Competitor1 | Agents | 90 |
| SWE | all | all | 2018-01-15 | Pc | Competitor1 | Agents | 90 |
| SWE | all | all | 2018-01-22 | Health | Competitor1 | Agents | 90 |
| SWE | all | all | 2018-01-22 | Life | Competitor1 | Agents | 90 |
| SWE | all | all | 2018-01-22 | Pc | Competitor1 | Agents | 90 |
* **Wide Format** (Useful for spreadsheets): Columns represent combinations of Product and Channel, with rows as dates. The first few rows define the meta data for the column (e.g., Country, Region, Competitor, ...).
| Country | SWE | SWE | SWE |
| ---------- | ----------- | ----------- | ----------- |
| Region | all | all | all |
| Product | Health | Life | Pc |
| Channel | Agents | Agents | Agents |
| Grouping | all | all | all |
| Competitor | Competitor1 | Competitor1 | Competitor1 |
| 2018-01-08 | 90 | 90 | 90 |
| 2018-01-15 | 90 | 90 | 90 |
| 2018-01-22 | 90 | 90 | 90 |
| 2018-01-29 | 90 | 90 | 90 |
| 2018-02-05 | 90 | 90 | 90 |
## Best Practices [#best-practices]
* **Consistency:** Ensure dates align with your project's periodicity (e.g., weekly data if the project is set to weekly granularity). Mismatched granularity will cause upload errors.
* **Data Quality:** Check for outliers, missing values, or inconsistencies before upload. Use the [Activities](../../Activities) dashboard to visualize and validate post-upload.
* **Granularity Alignment:** All data in a project must match the chosen periodicity (set during project creation). For details, see [Projects](../../Projects).
* **Competitor Tracking:** Include multiple competitors and channels for comprehensive analysis. Use clear, consistent naming for Competitor, Product, and Channel fields to enable easy filtering and comparison.
For uploading instructions, see [Upload Data](../Uploads). If you encounter issues, contact support or refer to the [API](../../API) for programmatic uploads.
# Competitor Media
Competitor media data tracks investments in advertising and media channels by your competitors, including groupings by product, media type, and other criteria. This includes spends on channels like Display, Facebook, Google, TV, or print. Media groupings allow for segmentation to analyze specific campaigns or strategies.
Sourced from market intelligence tools, ad tracking services, or third-party reports, this data helps Alviss AI model how competitors' advertising affects market dynamics, your sales, KPIs, and competitive positioning. For example, it can reveal how a rival's increased digital spend impacts your demand, enabling better attributions, simulations, predictions, and optimizations. Note: Only monetary investments are supported—convert metrics like GRPs (Gross Rating Points), Reach, Clicks, or Impressions to equivalent investment values before upload.
## Data Requirements [#data-requirements]
The Competitor Media Data file must include the following columns (headers). All columns are required unless marked as optional:
* **[Country](../Format/Country)** (string, required): A three-letter country code per ISO 3166 standard (e.g., "SWE" for Sweden), indicating where the media investment occurred.
* **[Region](../Format/Region)** (string, optional, defaults to "all"): The region within the country (e.g., "all" for nationwide or a specific ISO 3166-2 code like "SE-AB" for Stockholm County in Sweden).
* **[Date](../Format/Date)** (date, required): The date of the media investment in ISO 8601 format (YYYY-MM-DD).
* **Product** (string, optional, defaults to "all"): The name or identifier of the product associated with the investment (e.g., "Brand", "Pc", "Life").
* **Media** (string, optional, defaults to "all"): The media type or channel (e.g., "Display", "Facebook", "Google", "TVConventional").
* **Investment** (float, required): The investment amount in local currency (e.g., 107204). Use a period (.) as the decimal separator. Handle missing or zero values explicitly—Alviss AI will flag inconsistencies during upload.
* **[Grouping](../Format/Grouping)** (string, optional, defaults to "all"): For additional segmentation, such as product categories, demographics, or sales territories.
* **Competitor** (string, required): The name or identifier of the competitor company (e.g., "Competitor1").
* **Campaign** (string, optional, defaults to "all"): The campaign name or identifier associated with the media investment (e.g., "Campaign-2018").
* **Channel** (string, optional, defaults to "Other"): A higher-level channel grouping for the media. **Must be one of the following values (exact text):** "TV", "Radio", "Paid Search", "Paid Branded Search", "Paid Generic Search", "Social Media", "Display Ads", "Print", "Outdoor (OOH)", "Email", "Influencer", "Affiliate", "Organic Search", "Video Ads", "Direct Mail", "Partnerships", "Podcast", "Streaming Audio", "Mobile In-App", "Native Ads", "Events Sponsorship", "Content Marketing", "Cinema", "Magazine", "Connected TV", "Video On Demand", "Other".
Only monetary investments are supported. Convert non-monetary metrics (e.g., GRPs, Reach, Clicks) to equivalent investment values before uploading.
Only the following characters are allowed when enter text values: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
## Supported Formats [#supported-formats]
Data can be uploaded in **long** (tidy) or **wide** (pivoted) format. Choose based on your data pipeline:
* **Long Format** (Recommended for flexibility): Each row represents a single observation (one investment per competitor, product, media, date, etc.).
| Country | Region | Date | Product | Media | Investment | Grouping | Competitor | Campaign | Channel |
| ------- | ------ | ---------- | ------- | -------------- | ---------- | -------- | ----------- | ------------- | ------------ |
| SWE | all | 2018-01-08 | Pc | Display | 0 | all | Competitor1 | Campaign-2018 | Display Ads |
| SWE | all | 2018-01-08 | Pc | Facebook | 0 | all | Competitor1 | Campaign-2018 | Social Media |
| SWE | all | 2018-01-08 | Life | Google | 253 | all | Competitor1 | Campaign-2018 | Paid Search |
| SWE | all | 2018-01-08 | Pc | Google | 6332 | all | Competitor1 | Campaign-2018 | Paid Search |
| SWE | all | 2018-01-08 | Pc | TVConventional | 0 | all | Competitor1 | Campaign-2018 | TV |
| SWE | all | 2018-01-15 | Pc | Display | 0 | all | Competitor1 | Campaign-2018 | Display Ads |
| SWE | all | 2018-01-15 | Pc | Facebook | 0 | all | Competitor1 | Campaign-2018 | Social Media |
* **Wide Format** (Useful for spreadsheets): Columns represent combinations of Product and Media, with rows as dates. The first rows define fixed attributes (e.g., Country, Region, Competitor, Campaign, Channel).
| Country | SWE | SWE | SWE | SWE | SWE |
| ---------- | ------------- | ------------- | ------------- | ------------- | -------------- |
| Region | all | all | all | all | all |
| Product | Pc | Pc | Life | Pc | Pc |
| Media | Display | Facebook | Google | Google | TVConventional |
| Grouping | all | all | all | all | all |
| Competitor | Competitor1 | Competitor1 | Competitor1 | Competitor1 | Competitor1 |
| Campaign | Campaign-2018 | Campaign-2018 | Campaign-2018 | Campaign-2018 | Campaign-2018 |
| Channel | Display Ads | Social Media | Paid Search | Paid Search | TV |
| 2018-01-08 | 0 | 0 | 253 | 6332 | 0 |
| 2018-01-15 | 0 | 0 | 295 | 14874 | 0 |
| 2018-01-22 | 0 | 0 | 327 | 11880 | 0 |
| 2018-01-29 | 0 | 0 | 359 | 10565 | 0 |
| 2018-02-05 | 0 | 0 | 348 | 15873 | 0 |
## Best Practices [#best-practices]
* **Consistency:** Ensure dates align with your project's periodicity (e.g., weekly data if the project is set to weekly granularity). Mismatched granularity will cause upload errors.
* **Data Quality:** Check for outliers, missing values, or inconsistencies before upload. Use the [Activities](../../Activities) dashboard to visualize and validate post-upload.
* **Granularity Alignment:** All data in a project must match the chosen periodicity (set during project creation). For details, see [Projects](../../Projects).
* **Competitor Tracking:** Include multiple competitors, products, and media types for comprehensive analysis. Use clear, consistent naming for Competitor, Product, and Media fields to enable easy filtering and comparison.
* **Currency and Units:** Investments should be in local currency. If converting from other currencies, apply consistent exchange rates. Normalize non-investment metrics (e.g., GRPs) using standard industry formulas or estimates.
For uploading instructions, see [Upload Data](../Uploads). If you encounter issues, contact support or refer to the [API](../../API) for programmatic uploads.
# Competitor Price
Competitor price data captures pricing information for your competitors' products or services, including per-unit prices over time. This can include average selling prices, promotional discounts, or standard rates for comparable offerings in the market.
Sourced from market research, price tracking tools, public data, or third-party providers, this data enables Alviss AI to model price elasticity, competitive pricing effects on your sales, demand forecasting, and market share dynamics. For example, it can quantify how a competitor's price drop impacts your KPIs, supporting more accurate attributions, simulations, predictions, and optimizations. By incorporating competitor prices, you can refine pricing strategies and respond to market changes effectively.
## Data Requirements [#data-requirements]
The Competitor Price Data file must include the following columns (headers). All columns are required unless marked as optional:
* **[Country](../Format/Country)** (string, required): A three-letter country code per ISO 3166 standard (e.g., "SWE" for Sweden), indicating where the pricing applies.
* **[Region](../Format/Region)** (string, optional, defaults to "all"): The region within the country (e.g., "all" for nationwide or a specific ISO 3166-2 code like "SE-AB" for Stockholm County in Sweden).
* **[Grouping](../Format/Grouping)** (string, optional, defaults to "all"): For additional segmentation, such as product categories, demographics, or sales territories.
* **[Date](../Format/Date)** (date, required): The date the price was observed or effective in ISO 8601 format (YYYY-MM-DD).
* **Competitor** (string, required): The name or identifier of the competitor company (e.g., "Competitor1").
* **Product** (string, optional, defaults to "all"): The name or identifier of the product or service (e.g., "Health", "Life", "Pc").
* **PricePerUnit** (float, required): The price per unit in local currency (e.g., 294.00). Use a period (.) as the decimal separator. Handle missing values with `NaN` or blanks—Alviss AI will flag inconsistencies during upload.
Only the following characters are allowed when enter text values: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
## Supported Formats [#supported-formats]
Data can be uploaded in **long** (tidy) or **wide** (pivoted) format. Choose based on your data pipeline:
* **Long Format** (Recommended for flexibility): Each row represents a single observation (one price per competitor, product, date, etc.).
| Country | Region | Grouping | Date | Competitor | Product | PricePerUnit |
| ------- | ------ | -------- | ---------- | ----------- | ------- | ------------------ |
| SWE | all | all | 2018-01-08 | Competitor1 | Health | 294.00226025399996 |
| SWE | all | all | 2018-01-08 | Competitor1 | Life | 1612.55713923 |
| SWE | all | all | 2018-01-08 | Competitor1 | Pc | 442.507963842 |
| SWE | all | all | 2018-01-15 | Competitor1 | Health | 317.18127274200003 |
| SWE | all | all | 2018-01-15 | Competitor1 | Life | 4245.22609308 |
| SWE | all | all | 2018-01-15 | Competitor1 | Pc | 387.259558362 |
* **Wide Format** (Useful for spreadsheets): Columns represent combinations of Competitor and Product, with rows as dates. The first few rows define fixed attributes (e.g., Country, Region).
| Country | SWE | SWE | SWE | SWE | SWE | SWE |
| ---------- | ------------- | ------------- | ------------- | -------------- | -------------- | -------------- |
| Region | all | all | all | all | all | all |
| Product | Health | Life | Pc | Health | Life | Pc |
| Grouping | all | all | all | all | all | all |
| Competitor | Competitor1 | Competitor1 | Competitor1 | Competitor2 | Competitor2 | Competitor2 |
| 2018-01-08 | 294.002260254 | 1612.55713923 | 442.507963842 | 235.2018082032 | 1290.045711384 | 354.0063710736 |
| 2018-01-15 | 317.181272742 | 4245.22609308 | 387.259558362 | 253.7450181936 | 3396.180874464 | 309.8076466896 |
| 2018-01-22 | 231.454679661 | 1865.98471716 | 338.242985001 | 185.1637437288 | 1492.787773728 | 270.5943880008 |
| 2018-01-29 | 248.441386896 | 3247.18608348 | 279.878663421 | 198.7531095168 | 2597.748866784 | 223.9029307368 |
| 2018-02-05 | 292.951013094 | 1960.04017647 | 281.936195856 | 234.3608104752 | 1568.032141176 | 225.5489566848 |
## Best Practices [#best-practices]
* **Consistency:** Ensure dates align with your project's periodicity (e.g., weekly data if the project is set to weekly granularity). Mismatched granularity will cause upload errors.
* **Data Quality:** Check for outliers, missing values, or inconsistencies before upload. Use the [Activities](../../Activities) dashboard to visualize and validate post-upload.
* **Granularity Alignment:** All data in a project must match the chosen periodicity (set during project creation). For details, see [Projects](../../Projects).
* **Competitor Tracking:** Include multiple competitors and products for comprehensive analysis. Use clear, consistent naming for Competitor and Product fields to enable easy filtering and comparison.
* **Currency and Units:** Prices should be in local currency. If converting from other currencies, apply consistent exchange rates. Specify if prices are average, minimum, or promotional in metadata.
* **Integration with Models:** Reference competitor prices as drivers in attribution models to account for price competition. Combine with your own pricing data, [competitor media](./Competitor%20Media), [competitor brand](./Competitor%20Brand), or [competitor distribution](./Competitor%20Distribution) for holistic insights. Use in the [Basic Model Builder](../../Models/Basic%20Model%20Builder) or \[Advanced Model Builder]\(../../Models/Advanced Model Builder/Advanced Model Builder).
For uploading instructions, see [Upload Data](../Uploads). If you encounter issues, contact support or refer to the [API](../../API) for programmatic uploads.
# Customer Experience
Customer experience (CX) data tracks investments and efforts aimed at improving customer interactions, satisfaction, and loyalty. The primary focus is on monetary investments (e.g., in IT infrastructure, human resources, training, or other initiatives) to enable ROI estimation through modeling. This data helps quantify how CX enhancements contribute to business outcomes like retention, sales uplift, or KPI improvements.
CX metrics (e.g., Net Promoter Score (NPS), Voice of Customer (VOC), satisfaction scores) should be included in the [Brand](./Brand) file instead, as they represent outcomes rather than inputs. Sourced from internal financial records, project budgets, or CRM systems, this data allows Alviss AI to incorporate CX investments as drivers in attributions, simulations, predictions, and optimizations. For example, it can model the impact of investing in customer support teams on overall revenue.
## Data Requirements [#data-requirements]
The Customer Experience Data file must include the following columns (headers). All columns are required unless marked as optional:
* **[Country](../Format/Country)** (string, required): A three-letter country code per ISO 3166 standard (e.g., "SWE" for Sweden), indicating where the investment occurred.
* **[Region](../Format/Region)** (string, optional, defaults to "all"): The region within the country (e.g., "all" for nationwide or a specific ISO 3166-2 code like "SE-AB" for Stockholm County in Sweden).
* **[Grouping](../Format/Grouping)** (string, optional, defaults to "all"): For additional segmentation, such as product categories, demographics, or sales territories.
* **[Date](../Format/Date)** (date, required): The date of the investment in ISO 8601 format (YYYY-MM-DD).
* **Product** (string, optional, defaults to "all"): The name or identifier of the product or service associated with the investment (e.g., "Brand", "Pc", "Life").
* **Channel** (string, required): The type of CX activity or initiative (e.g., "IT" for technology investments, "Human" for staffing or training, "Non Human" for automated systems).
* **Investment** (float, required): The investment amount in local currency (e.g., 107204). Use a period (.) as the decimal separator. Handle missing or zero values explicitly—Alviss AI will flag inconsistencies during upload.
Only the following characters are allowed when enter text values: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
## Supported Formats [#supported-formats]
Data can be uploaded in **long** (tidy) or **wide** (pivoted) format. Choose based on your data pipeline:
* **Long Format** (Recommended for flexibility): Each row represents a single observation (one investment per product, channel, date, etc.).
| Country | Region | Grouping | Date | Product | Channel | Investment |
| ------- | ------ | -------- | ---------- | ------- | ------- | ---------- |
| SWE | all | all | 2018-01-08 | Brand | IT | 107204 |
| SWE | all | all | 2018-01-08 | Pc | Human | 0 |
| SWE | all | all | 2018-01-08 | Brand | IT | 0 |
| SWE | all | all | 2018-01-08 | Pc | Human | 0 |
| SWE | all | all | 2018-01-08 | Brand | IT | 2342 |
| SWE | all | all | 2018-01-08 | Life | IT | 253 |
| SWE | all | all | 2018-01-08 | Pc | Human | 6332 |
* **Wide Format** (Useful for spreadsheets): Columns represent combinations of Product and Channel, with rows as dates. The first few rows define fixed attributes (e.g., Country, Region).
| Country | SWE | SWE | SWE | SWE | SWE | SWE | SWE |
| ---------- | ------ | --- | ----- | ----- | --------- | --------- | --------- |
| Region | all | all | all | all | all | all | all |
| Product | Brand | Pc | Brand | Pc | Brand | Life | Pc |
| Channel | IT | IT | Human | Human | Non Human | Non Human | Non Human |
| Grouping | all | all | all | all | all | all | all |
| 2018-01-08 | 107204 | 0 | 0 | 0 | 2342 | 253 | 6332 |
| 2018-01-15 | 0 | 0 | 0 | 0 | 2134 | 295 | 14874 |
| 2018-01-22 | 0 | 0 | 0 | 0 | 2097 | 327 | 11880 |
| 2018-01-29 | 0 | 0 | 0 | 0 | 2324 | 359 | 10565 |
## Best Practices [#best-practices]
* **Consistency:** Ensure dates align with your project's periodicity (e.g., weekly data if the project is set to weekly granularity). Mismatched granularity will cause upload errors.
* **Data Quality:** Check for outliers, missing values, or inconsistencies before upload. Use the [Activities](../../Activities) dashboard to visualize and validate post-upload.
* **Granularity Alignment:** All data in a project must match the chosen periodicity (set during project creation). For details, see [Projects](../../Projects).
* **Channel Definition:** Use consistent and descriptive channel names (e.g., "IT", "Human", "Non Human") to reflect investment types. This aids in modeling different CX levers.
## Common Issues and Troubleshooting [#common-issues-and-troubleshooting]
* **Metrics vs. Investments:** Avoid including outcome metrics here—route them to [Brand](./Brand) to prevent model confusion.
* **Differentiation from Other Investments:** Ensure CX data is uploaded separately from media or other spends to maintain clear modeling distinctions.
For uploading instructions, see [Upload Data](../Uploads). If you encounter issues, contact support or refer to the [API](../../API) for programmatic uploads.
# Distribution
Distribution data tracks metrics related to your company's physical or operational presence for selling and distributing products or services, such as the number of stores, sales agents, offices, or partners. This information is crucial for Alviss AI to model how your distribution network influences sales, market coverage, and overall business performance.
Examples of distribution metrics include the count of retail outlets, authorized dealers, or online fulfillment centers. Sourced from internal operations data, CRM systems, or supply chain reports, this data allows Alviss AI to incorporate distribution as a driver in attributions, simulations, predictions, and optimizations. For instance, it can quantify how expanding your agent network affects demand or revenue, enabling data-driven decisions on resource allocation and growth strategies.
## Data Requirements [#data-requirements]
The Distribution Data file must include the following columns (headers). All columns are required unless marked as optional:
* **[Country](../Format/Country)** (string, required): A three-letter country code per ISO 3166 standard (e.g., "SWE" for Sweden), indicating where the distribution metrics apply.
* **[Region](../Format/Region)** (string, optional, defaults to "all"): The region within the country (e.g., "all" for nationwide or a specific ISO 3166-2 code like "SE-AB" for Stockholm County in Sweden).
* **[Grouping](../Format/Grouping)** (string, optional, defaults to "all"): For additional segmentation, such as product categories, demographics, or sales territories.
* **[Date](../Format/Date)** (date, required): The start date of the period for the distribution metrics in ISO 8601 format (YYYY-MM-DD).
* **Product** (string, optional, defaults to "all"): The name or identifier of the product associated with the distribution (e.g., "Health").
* **Channel** (string, required): The distribution channel (e.g., "Agents", "Stores", "Offices").
* **Value** (integer, required): The count of distribution units (e.g., 90). Use whole numbers; handle missing values with blanks or zeros—Alviss AI will flag inconsistencies during upload.
Only the following characters are allowed when enter text values: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
## Supported Formats [#supported-formats]
Data can be uploaded in **long** (tidy) or **wide** (pivoted) format. Choose based on your data pipeline:
* **Long Format** (Recommended for flexibility): Each row represents a single observation (one value per product, channel, date, etc.).
| Country | Region | Grouping | Date | Product | Channel | Value |
| :------ | :----- | :------- | :--------- | :------ | :------ | ----: |
| SWE | all | all | 2018-01-07 | Health | Agents | 90 |
| SWE | all | all | 2018-01-07 | Life | Agents | 90 |
| SWE | all | all | 2018-01-07 | Pc | Agents | 90 |
| SWE | all | all | 2018-01-14 | Health | Agents | 90 |
| SWE | all | all | 2018-01-14 | Life | Agents | 90 |
| SWE | all | all | 2018-01-14 | Pc | Agents | 90 |
* **Wide Format** (Useful for spreadsheets): Columns represent combinations of Product and Channel, with rows as dates. The first few rows define fixed attributes (e.g., Country, Region).
| Country | SWE | SWE | SWE |
| ---------- | ------ | ------ | ------ |
| Region | all | all | all |
| Product | Health | Life | Pc |
| Channel | Agents | Agents | Agents |
| Grouping | all | all | all |
| 2018-01-08 | 90 | 90 | 90 |
| 2018-01-15 | 90 | 90 | 90 |
## Best Practices [#best-practices]
* **Consistency:** Ensure dates align with your project's periodicity (e.g., weekly data if the project is set to weekly granularity). Mismatched granularity will cause upload errors.
* **Data Quality:** Check for outliers, missing values, or inconsistencies before upload. Use the [Activities](../../Activities) dashboard to visualize and validate post-upload.
* **Granularity Alignment:** All data in a project must match the chosen periodicity (set during project creation). For details, see [Projects](../../Projects).
* **Channel and Product Tracking:** Use clear, consistent naming for Channel and Product fields to enable easy filtering and comparison across segments.
For uploading instructions, see [Upload Data](../Uploads). If you encounter issues, contact support or refer to the [API](../../API) for programmatic uploads.
# Events
Events data captures time-bound occurrences that may impact business operations, such as Force Majeure events (e.g., natural disasters), strikes, website outages, or other extraordinary circumstances. These events span a defined period and can be used to model disruptions or anomalies in sales, demand, or other KPIs.
Sourced from internal logs, news reports, or operational records, this data allows Alviss AI to incorporate event-based controls in modeling. For example, it can quantify the impact of a system downtime on revenue, helping to isolate external factors in attributions, simulations, predictions, and optimizations. By including events, models can account for non-recurring influences, improving accuracy and providing insights into resilience strategies.
## Data Requirements [#data-requirements]
The Events Data file must include the following columns (headers). All columns are required unless marked as optional:
* **[Country](../Format/Country)** (string, required): A three-letter country code per ISO 3166 standard (e.g., "SWE" for Sweden), indicating where the event occurred.
* **[Region](../Format/Region)** (string, optional, defaults to "all"): The region within the country (e.g., "all" for nationwide or a specific ISO 3166-2 code like "SE-AB" for Stockholm County in Sweden).
* **[Grouping](../Format/Grouping)** (string, optional, defaults to "all"): For additional segmentation, such as product categories, demographics, or sales territories.
* **StartDate** (date, required): The start date of the event in ISO 8601 format (YYYY-MM-DD).
* **EndDate** (date, required): The end date of the event in ISO 8601 format (YYYY-MM-DD). This can be the same as StartDate for single-day events.
* **Event** (string, required): The name or identifier of the event (e.g., "Website down", "Strike"). The same event can span multiple rows if it affects different locations or groupings.
## Supported Formats [#supported-formats]
Data can be uploaded in **long** (tidy) or **wide** (pivoted) format. Choose based on your data pipeline:
* **Long Format** (Recommended for flexibility): Each row represents a single event instance (one event per location, grouping, date range).
| Country | Region | Grouping | StartDate | EndDate | Event |
| ------- | ------ | -------- | ---------- | ---------- | ------------ |
| SWE | all | all | 2018-01-08 | 2018-01-10 | Website down |
| UKR | all | all | 2019-10-21 | 2019-10-24 | Strike |
* **Wide Format** (Useful for spreadsheets): Columns represent combinations of Country, Region, Event, and Metric (StartDate/EndDate), with rows containing the date values. The first few rows define fixed attributes.
| Country | SWE | UKR | SWE | UKR |
| -------- | ------------ | ---------- | ------------ | ---------- |
| Region | all | all | all | all |
| Event | Website down | Strike | Website down | Strike |
| Grouping | all | all | all | all |
| Metric | StartDate | StartDate | EndDate | EndDate |
| | 2018-01-08 | 2019-10-21 | 2018-01-10 | 2019-10-24 |
## Best Practices [#best-practices]
* **Consistency:** Ensure dates align with your project's periodicity (e.g., weekly events if the project is set to weekly granularity). Overlapping or mismatched dates may require aggregation.
* **Data Quality:** Verify event dates for accuracy and completeness. Use the [Activities](../../Activities) dashboard to cross-reference with sales or other data for validation.
* **Granularity Alignment:** All data in a project must match the chosen periodicity (set during project creation). For details, see [Projects](../../Projects).
* **Event Naming:** Use clear, consistent event names to enable easy filtering. Categorize events (e.g., "Operational: Website down") for advanced grouping in models.
For uploading instructions, see [Upload Data](../Uploads). If you encounter issues, contact support or refer to the [API](../../API) for programmatic uploads.
# Extra
Extra data encompasses any additional variables or metrics that do not fit neatly into other predefined categories (e.g., brand, media, sales). This flexible file type allows you to include custom indicators such as agreements, supply chain performance, inquiries, or other business-specific data points that may influence your models. With the optional `Category` field, you can also group variables into higher-level buckets (e.g., "Operations", "Support") to make reporting and filtering easier.
Sourced from internal systems, external reports, or custom trackers, this data enables Alviss AI to incorporate unique drivers into attributions, simulations, predictions, and optimizations. For example, it can model how supply chain disruptions or inquiry volumes affect sales, providing a way to capture niche factors for more tailored insights. Use this category sparingly—prioritize fitting data into standard types when possible to maintain consistency.
## Data Requirements [#data-requirements]
The Extra Data file must include the following columns (headers). All columns are required unless marked as optional:
* **[Country](../Format/Country)** (string, required): A three-letter country code per ISO 3166 standard (e.g., "SWE" for Sweden), indicating where the indicators were collected.
* **[Region](../Format/Region)** (string, optional, defaults to "all"): The region within the country (e.g., "all" for nationwide or a specific ISO 3166-2 code like "SE-AB" for Stockholm County in Sweden).
* **[Grouping](../Format/Grouping)** (string, optional, defaults to "all"): For additional segmentation, such as product categories, demographics, or sales territories.
* **[Date](../Format/Date)** (date, required): The collection date in ISO 8601 format (YYYY-MM-DD).
* **Variable** (string, required): The name or identifier of the custom variable (e.g., "Agreements", "SupplyChain", "Inquiries").
* **Value** (float, required): The value of the variable (e.g., 21.33). Use consistent units; handle missing values with `NaN` or blanks—Alviss AI will flag inconsistencies during upload.
* **Category** (string, optional, defaults to "all"): A high-level grouping for the variable (e.g., "Operations", "Support").
Only the following characters are allowed when enter text values: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
## Supported Formats [#supported-formats]
Data can be uploaded in **long** (tidy) or **wide** (pivoted) format. Choose based on your data pipeline:
* **Long Format** (Recommended for flexibility): Each row represents a single observation (one value per variable, date, etc.).
| Country | Region | Date | Variable | Value | Grouping | Category |
| ------- | ------ | ---------- | ----------- | ------------------ | -------- | ---------- |
| SWE | all | 2018-01-08 | Agreements | 21.33469940823065 | all | Operations |
| SWE | all | 2018-01-08 | SupplyChain | 84.44735037052821 | all | Operations |
| SWE | all | 2018-01-08 | Inquiries | 10919.681974347444 | all | Support |
* **Wide Format** (Useful for spreadsheets): Columns represent different variables, with rows as dates. The first few rows define fixed attributes (e.g., Country, Region, Category).
| Country | SWE | SWE | SWE |
| ---------- | ------------------ | ----------------- | ------------------ |
| Region | all | all | all |
| Variable | Agreements | SupplyChain | Inquiries |
| Grouping | all | all | all |
| Category | Operations | Operations | Support |
| 2018-01-08 | 21.33469940823065 | 84.44735037052821 | 10919.681974347444 |
| 2018-01-15 | 21.371987400471085 | 84.42400561069927 | 10586.118505333174 |
| 2018-01-22 | 21.37077515290617 | 81.58310396849542 | 10843.546180775744 |
| 2018-01-29 | 20.60077934829962 | 84.86239064581484 | 10659.81858502802 |
| 2018-02-05 | 20.345510855068166 | 83.37618357415872 | 10179.119419190954 |
## Best Practices [#best-practices]
* **Consistency:** Ensure dates align with your project's periodicity (e.g., weekly data if the project is set to weekly granularity). Mismatched granularity will cause upload errors.
* **Data Quality:** Check for outliers, missing values, or inconsistencies before upload. Use the [Activities](../../Activities) dashboard to visualize and validate post-upload.
* **Granularity Alignment:** All data in a project must match the chosen periodicity (set during project creation). For details, see [Projects](../../Projects).
* **Variable Naming:** Use clear, descriptive names for variables to facilitate model interpretation and filtering. Avoid duplicates with standard categories.
For uploading instructions, see [Upload Data](../Uploads). If you encounter issues, contact support or refer to the [API](../../API) for programmatic uploads.
# Macro
Macroeconomic data includes indicators that reflect broader economic conditions, such as unemployment rates, consumer confidence indexes (CCI), consumer price indexes (CPI), interest rates, currency exchange rates, happiness indexes, or GDP growth. These factors can significantly influence consumer behavior and business performance—for instance, high unemployment might reduce willingness to purchase non-essential goods like new cars, while rising interest rates could affect borrowing and spending.
Often sourced from public databases (e.g., government statistics, World Bank, OECD), financial reports, or third-party providers, this data enables Alviss AI to model external economic impacts on your KPIs. By incorporating macroeconomic indicators, you can isolate cyclical or structural effects in attributions, simulations, predictions, and optimizations, leading to more robust strategies that account for market conditions beyond your control.
## Data Requirements [#data-requirements]
The Macroeconomic Data file must include the following columns (headers). All columns are required unless marked as optional:
* **[Country](../Format/Country)** (string, required): A three-letter country code per ISO 3166 standard (e.g., "SWE" for Sweden), indicating where the indicators were collected.
* **[Region](../Format/Region)** (string, optional, defaults to "all"): The region within the country (e.g., "all" for nationwide or a specific ISO 3166-2 code like "SE-AB" for Stockholm County in Sweden).
* **[Grouping](../Format/Grouping)** (string, optional, defaults to "all"): For additional segmentation, such as product categories, demographics, or sales territories.
* **[Date](../Format/Date)** (date, required): The collection date in ISO 8601 format (YYYY-MM-DD).
* **Indicator** (string, required): The name of the macroeconomic indicator (e.g., "Unemployment", "Happiness", "CCI", "Interest Rate").
* **Value** (float, required): The value of the indicator (e.g., 0.212). Use consistent units (e.g., rates as decimals or percentages; specify in metadata if needed). Handle missing values with `NaN` or blanks—Alviss AI will flag inconsistencies during upload.
Only the following characters are allowed when enter text values: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
## Supported Formats [#supported-formats]
Data can be uploaded in **long** (tidy) or **wide** (pivoted) format. Choose based on your data pipeline:
* **Long Format** (Recommended for flexibility): Each row represents a single observation (one value per indicator, date, etc.).
| Country | Region | Grouping | Date | Indicator | Value |
| :------ | :----- | :------- | :--------- | :----------- | ----------: |
| SWE | all | all | 2018-01-07 | Unemployment | 0.2123493 |
| SWE | all | all | 2018-01-07 | Happiness | 0.8387580 |
| SWE | all | all | 2018-01-07 | CCI | 108.1410075 |
| SWE | all | all | 2018-01-14 | Unemployment | 0.2136844 |
| SWE | all | all | 2018-01-14 | Happiness | 0.8374786 |
| SWE | all | all | 2018-01-14 | CCI | 105.3537534 |
* **Wide Format** (Useful for spreadsheets): Columns represent different indicators, with rows as dates. The first few rows define fixed attributes (e.g., Country, Region).
| Country | SWE | SWE | SWE |
| ---------- | ------------ | ------------ | ----------- |
| Region | all | all | all |
| Indicator | Unemployment | Happiness | CCI |
| Grouping | all | all | all |
| 2018-01-08 | 0.2123492784 | 0.8387580455 | 108.1410075 |
| 2018-01-15 | 0.2136843525 | 0.8374786345 | 105.3537534 |
| 2018-01-22 | 0.2128232805 | 0.8154242335 | 107.6426854 |
| 2018-01-29 | 0.2059345445 | 0.8425253371 | 106.477429 |
| 2018-02-05 | 0.2029192976 | 0.8324368096 | 101.2852837 |
| 2018-02-12 | 0.2041849944 | 0.8752431161 | 109.793951 |
## Best Practices [#best-practices]
* **Consistency:** Ensure dates align with your project's periodicity (e.g., monthly data if the project is set to monthly granularity). Mismatched granularity will cause upload errors.
* **Data Quality:** Source from reliable providers and check for revisions or updates, as macroeconomic data is often preliminary and revised later. Use the [Activities](../../Activities) dashboard to visualize and validate post-upload.
* **Granularity Alignment:** All data in a project must match the chosen periodicity (set during project creation). For details, see [Projects](../../Projects).
* **Indicator Selection:** Choose relevant indicators based on your industry (e.g., CCI for consumer goods, interest rates for finance). Use clear, consistent naming for easy model integration.
For uploading instructions, see [Upload Data](../Uploads). If you encounter issues, contact support or refer to the [API](../../API) for programmatic uploads.
# Media
Media data captures investments in advertising and campaigns, including groupings by product, media type, campaign, and metrics like impressions or clicks. This encompasses all promotional activities, such as digital ads, TV spots, or social media campaigns, broken down by taxonomy relevant to your business (e.g., media groups, publishers, or channels).
All advertising contributes to sales and KPIs, so providing detailed investment data allows Alviss AI to model media effectiveness accurately. For campaigns targeting all products/services, use "all" in the Product field. Sourced from ad platforms (e.g., Google Ads, Facebook), agency reports, or internal trackers, this data enables quantification of ROI, channel performance, and campaign impacts in attributions, simulations, predictions, and optimizations. With the extended specification (Channel, Format, Device, TargetGroup, Creative, Category), it also supports richer taxonomy and more granular analysis (e.g., separating paid search from display, or online from offline).
## Data Requirements [#data-requirements]
The Media Data file must include the following columns (headers). All columns are required unless marked as optional:
* **[Country](../Format/Country)** (string, required): A three-letter country code per ISO 3166 standard (e.g., "SWE" for Sweden), indicating where the media investment occurred.
* **[Region](../Format/Region)** (string, optional, defaults to "all"): The region within the country (e.g., "all" for nationwide or a specific ISO 3166-2 code like "SE-AB" for Stockholm County in Sweden).
* **[Grouping](../Format/Grouping)** (string, optional, defaults to "all"): For additional segmentation, such as product categories, demographics, or sales territories.
* **[Date](../Format/Date)** (date, required): The date of the media activity in ISO 8601 format (YYYY-MM-DD).
* **Product** (string, optional, defaults to "all"): The name or identifier of the product/service targeted (e.g., "Brand", "Life"); defaults to "all" for broad campaigns.
* **Media** (string, required): A short identifier for the media placement or publisher (e.g., "Google", "Facebook", "TVConventional", "OOHSponsoringLFP").
* **Campaign** (string, optional, defaults to "all"): The campaign name (e.g., "Campaign-2018"); defaults to "all" if not campaign-specific.
* **Metric** (string, optional, defaults to "Investment"): The measurement type; must be one of: "Impression", "Investment", "GRP", "Reach", "Clicks", "Leads", "Gross".
* **Channel** (string, optional, defaults to "Other"): The marketing channel grouping for analysis. **Must be one of the following values (exact text):** "TV", "Radio", "Paid Search", "Paid Branded Search", "Paid Generic Search", "Social Media", "Display Ads", "Print", "Outdoor (OOH)", "Email", "Influencer", "Affiliate", "Organic Search", "Video Ads", "Direct Mail", "Partnerships", "Podcast", "Streaming Audio", "Mobile In-App", "Native Ads", "Events Sponsorship", "Content Marketing", "Cinema", "Magazine", "Connected TV", "Video On Demand", "Other".
* **Format** (string, optional, defaults to "all"): The ad format or placement type (e.g., "ad", "banner", "post", "30s").
* **Device** (string, optional, defaults to "all"): The primary device type (e.g., "search", "television", "outdoor").
* **TargetGroup** (string, optional, defaults to "all"): The target audience segment (e.g., "niche", "broad").
* **Creative** (string, optional, defaults to "all"): A descriptor of the creative type (e.g., "interactive", "visual").
* **Value** (float, required): The metric value (e.g., investment in local currency like 7204, or impressions like 107204). Use a period (.) as the decimal separator.
* **Category** (string, optional, defaults to "all"): A high-level classification such as "online" or "offline".
An "Investment" metric must always be provided for every unique combination of Country, Region, Grouping, Date, Product, Media, and Campaign.
For each unique combination of Country, Region, Grouping, Product, Media, and Campaign, an "Investment" is required, and optionally one other metric (e.g., "Impression"). The optional metric must be consistent across all dates for that combination.
Only the following characters are allowed when enter text values: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
## Supported Formats [#supported-formats]
Data can be uploaded in **long** (tidy) or **wide** (pivoted) format. Choose based on your data pipeline:
* **Long Format** (Recommended for flexibility): Each row represents a single observation (one metric per combination).
| Country | Region | Grouping | Date | Product | Media | Campaign | Metric | Channel | Format | Device | TargetGroup | Creative | Value | Category |
| :------ | :----- | :------- | :--------- | :------ | :--------------- | :------------ | :--------- | :------------ | :---------- | :--------- | :---------- | :---------- | -------: | :------- |
| SWE | all | all | 2018-01-08 | Life | Google | Campaign-2018 | Impression | Paid Search | ad | search | niche | interactive | 13724.05 | online |
| UKR | all | all | 2018-01-08 | Pc | Google | Campaign-2018 | Impression | Paid Search | ad | search | niche | interactive | 24901.93 | online |
| UKR | all | all | 2018-01-08 | Pc | Google | Campaign-2018 | Investment | Paid Search | ad | search | niche | interactive | 253.0 | online |
| SWE | all | all | 2018-01-08 | Pc | TVConventional | Campaign-2018 | GRP | TV | 60s | television | broad | visual | 0.0 | offline |
| SWE | all | all | 2018-01-08 | Pc | TVConventional | Campaign-2018 | Investment | TV | 60s | television | broad | visual | 0.0 | offline |
| UKR | all | all | 2018-01-08 | Life | OOHSponsoringLFP | Campaign-2018 | Investment | Outdoor (OOH) | sponsorship | outdoor | broad | visual | 0.0 | offline |
| SWE | all | all | 2018-01-08 | Pc | TVConventional | Campaign-2018 | Investment | TV | 30s | television | broad | visual | 0.0 | offline |
* **Wide Format** (Useful for spreadsheets): Columns represent combinations of Metric (and associated attributes), with rows as dates. The first few rows define fixed attributes (e.g., Country, Region, Product, Media, Channel, Format, Device, TargetGroup, Creative, Category).
| Country | SWE | UKR | UKR | SWE | SWE | UKR | SWE |
| ----------- | ------------- | ------------- | ------------- | -------------- | -------------- | ---------------- | -------------- |
| Region | all | all | all | all | all | all | all |
| Grouping | all | all | all | all | all | all | all |
| Product | Life | Pc | Pc | Pc | Pc | Life | Pc |
| Media | Google | Google | Google | TVConventional | TVConventional | OOHSponsoringLFP | TVConventional |
| Campaign | Campaign-2018 | Campaign-2018 | Campaign-2018 | Campaign-2018 | Campaign-2018 | Campaign-2018 | Campaign-2018 |
| Metric | Impression | Impression | Investment | GRP | Investment | Investment | Investment |
| Channel | Paid Search | Paid Search | Paid Search | TV | TV | Outdoor (OOH) | TV |
| Format | ad | ad | ad | 60s | 60s | sponsorship | 30s |
| Device | search | search | search | television | television | outdoor | television |
| TargetGroup | niche | niche | niche | broad | broad | broad | broad |
| Creative | interactive | interactive | interactive | visual | visual | visual | visual |
| Category | online | online | online | offline | offline | offline | offline |
| 2018-01-08 | 13724.05 | 24901.93 | 253.0 | 0.0 | 0.0 | 0.0 | 0.0 |
| 2018-01-15 | 17566.77 | 15341.08 | 295.0 | 0.0 | 0.0 | | 0.0 |
| 2018-01-22 | 16528.48 | 107114.48 | 2097.0 | 0.0 | 0.0 | | 0.0 |
| 2018-01-29 | 25439.77 | | | 0.0 | 0.0 | | 0.0 |
| 2018-02-05 | 20646.66 | 254716.86 | 2758.0 | 0.0 | 0.0 | | 0.0 |
## Best Practices [#best-practices]
* **Consistency:** Ensure dates align with your project's periodicity (e.g., daily data if the project is set to daily granularity). Mismatched granularity will cause upload errors.
* **Data Quality:** Check for outliers, missing values, or inconsistencies before upload. Always include "Investment" for every combination to enable ROI calculations. Use the [Activities](../../Activities) dashboard to visualize and validate post-upload.
* **Granularity Alignment:** All data in a project must match the chosen periodicity (set during project creation). For details, see [Projects](../../Projects).
* **Taxonomy and Grouping:** Define Media, Campaign, and Product consistently to reflect your business structure. This aids in filtering and aggregation during analysis.
For uploading instructions, see [Upload Data](../Uploads). If you encounter issues, contact support or refer to the [API](../../API) for programmatic uploads.
# Sales
Sales data is the core and most critical dataset in Alviss AI, as it represents actual business outcomes like revenue and volume. This file is the only required data source for modeling and must include units sold and price per unit; profit per unit is optional but recommended for advanced ROI analysis. It captures transactional details, enabling Alviss AI to model demand drivers, price elasticity, and performance trends.
Examples include daily/weekly sales volumes and average prices for products like insurance policies or consumer goods. Sourced from CRM systems, ERP software, point-of-sale records, or e-commerce platforms, this data forms the foundation for attributions (e.g., linking marketing to sales), simulations (e.g., "what if" price changes), predictions (e.g., forecasting demand), and optimizations (e.g., pricing strategies). Without accurate sales data, models cannot quantify impacts on KPIs, making it essential for all projects.
## Data Requirements [#data-requirements]
The Sales Data file must include the following columns (headers). All columns are required unless marked as optional:
* **[Country](../Format/Country)** (string, required): A three-letter country code per ISO 3166 standard (e.g., "SWE" for Sweden), indicating where the sales occurred.
* **[Region](../Format/Region)** (string, optional, defaults to "all"): The region within the country (e.g., "all" for nationwide or a specific ISO 3166-2 code like "SE-AB" for Stockholm County in Sweden).
* **[Grouping](../Format/Grouping)** (string, optional, defaults to "all"): For additional segmentation, such as sales channels, customer types, or product variants.
* **[Date](../Format/Date)** (date, required): The start date of the sales period in ISO 8601 format (YYYY-MM-DD).
* **Product** (string, required): The name or identifier of the product/service sold (e.g., "Health", "Life", "Pc").
* **UnitsSold** (integer or float, required): The number of units sold (e.g., 292). Can be fractional for weighted or averaged data; use integers for whole counts.
* **PricePerUnit** (float, optional): The average price per unit in local currency (e.g., 362.97). Use a period (.) as the decimal separator. Optional but recommended for revenue analysis.
* **ProfitPerUnit** (float, optional): The average profit per unit in local currency (e.g., 120.0). Include for margin-based analysis; omit if unavailable.
Only the following characters are allowed when enter text values: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
## Supported Formats [#supported-formats]
Data can be uploaded in **long** (tidy) or **wide** (pivoted) format. Choose based on your data pipeline:
* **Long Format** (Recommended for flexibility): Each row represents a single observation (one product per date, etc.).
| Country | Region | Grouping | Date | Product | UnitsSold | PricePerUnit | ProfitPerUnit |
| :------ | :----- | :------- | :--------- | :------ | --------: | -----------: | ------------: |
| SWE | all | all | 2018-01-07 | Health | 292.00 | 362.9658 | 120.0 |
| SWE | all | all | 2018-01-07 | Life | 1489.00 | 1990.8113 | 550.0 |
| SWE | all | all | 2018-01-07 | Pc | 30212.33 | 546.3061 | 220.0 |
| SWE | all | all | 2018-01-14 | Health | 275.00 | 391.5818 | 120.0 |
| SWE | all | all | 2018-01-14 | Life | 1359.00 | 5241.0199 | 550.0 |
| SWE | all | all | 2018-01-14 | Pc | 27306.00 | 478.0982 | 220.0 |
* **Wide Format** (Useful for spreadsheets): Columns represent combinations of Product and Metric (UnitsSold, PricePerUnit, etc.), with rows as dates. The first few rows define fixed attributes (e.g., Country, Region). Note: ProfitPerUnit can be added as additional columns if included.
| Country | SWE | SWE | SWE | SWE | SWE | SWE |
| ---------- | --------- | --------- | ----------- | ------------ | ------------ | ------------ |
| Region | all | all | all | all | all | all |
| Product | Health | Life | Pc | Health | Life | Pc |
| Grouping | all | all | all | all | all | all |
| Metric | UnitsSold | UnitsSold | UnitsSold | PricePerUnit | PricePerUnit | PricePerUnit |
| 2018-01-08 | 292 | 1489 | 30212.33333 | 362.9657534 | 1990.811283 | 546.3061282 |
| 2018-01-15 | 275 | 1359 | 27306 | 391.5818182 | 5241.019868 | 478.0982202 |
| 2018-01-22 | 359 | 1431 | 25467 | 285.7465181 | 2303.684836 | 417.5839321 |
| 2018-01-29 | 411 | 1481 | 22027 | 306.7177616 | 4008.871708 | 345.5292141 |
| 2018-02-05 | 533 | 2382 | 50881 | 361.6679174 | 2419.802687 | 348.0693776 |
## Best Practices [#best-practices]
* **Consistency:** Ensure dates align with your project's periodicity (e.g., weekly sales if the project is set to weekly granularity). Mismatched granularity will cause upload errors. Use average prices for aggregated periods to reflect true economics.
* **Data Quality:** Verify for outliers (e.g., negative units), missing values, or inconsistencies before upload. Include ProfitPerUnit when possible for margin-focused insights. Use the [Activities](../../Activities) dashboard to visualize and validate post-upload.
* **Granularity Alignment:** All data in a project must match the chosen periodicity (set during project creation). For details, see [Projects](../../Projects).
* **Product and Grouping:** Use consistent naming for Product and Grouping to enable segmentation. If sales span multiple products, allocate appropriately or use "all".
## Common Issues and Troubleshooting [#common-issues-and-troubleshooting]
* **Fractional Units:** Acceptable for averaged data, but ensure they make sense for your business (e.g., partial policies); round if whole counts are required.
* **Optional Fields:** Omitting ProfitPerUnit is fine, but including it enhances model depth—add it later via dataset updates if needed.
For uploading instructions, see [Upload Data](../Uploads). If you encounter issues, contact support or refer to the [API](../../API) for programmatic uploads.
# Visits
Visits data tracks traffic metrics, such as website visits, store footfall, or other forms of consumer engagement that indicate interest or exposure to your business. This includes sessions from various channels like direct access, paid search, or email campaigns, helping to understand how traffic correlates with conversions and sales.
Monitoring visits is key to analyzing consumer behavior and funnel efficiency. Alviss AI uses this data to model how traffic scales with outcomes like revenue, quantifying the impact of marketing channels on demand. For example, it can reveal how organic search visits drive in-store purchases, supporting optimizations for acquisition strategies. Sourced from analytics tools (e.g., Google Analytics for web, sensors/counters for physical stores), this data enhances attributions, simulations, predictions, and response curves by linking upstream engagement to downstream results.
## Data Requirements [#data-requirements]
The Visits Data file must include the following columns (headers). All columns are required unless marked as optional:
* **[Country](../Format/Country)** (string, required): A three-letter country code per ISO 3166 standard (e.g., "SWE" for Sweden), indicating where the visit metrics were collected.
* **[Region](../Format/Region)** (string, optional, defaults to "all"): The region within the country (e.g., "all" for nationwide or a specific ISO 3166-2 code like "SE-AB" for Stockholm County in Sweden).
* **[Grouping](../Format/Grouping)** (string, optional, defaults to "all"): For additional segmentation, such as product categories, demographics, or sales territories.
* **[Date](../Format/Date)** (date, required): The collection date in ISO 8601 format (YYYY-MM-DD).
* **Channel** (string, required): The traffic source or channel (e.g., "BrandedPaidSearch", "Direct", "Display", "Email", "GenericPaidSearch", "OrganicSearch").
* **Visits** (float, required): The number of visits (e.g., 11339). Can be fractional for weighted or averaged data; handle missing values with blanks or zeros—Alviss AI will flag inconsistencies during upload.
Only the following characters are allowed when enter text values: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
## Supported Formats [#supported-formats]
Data can be uploaded in **long** (tidy) or **wide** (pivoted) format. Choose based on your data pipeline:
* **Long Format** (Recommended for flexibility): Each row represents a single observation (one channel per date, etc.).
| Country | Region | Grouping | Date | Channel | Visits |
| :------ | :----- | :------- | :--------- | :---------------- | -----: |
| SWE | all | all | 2018-01-07 | BrandedPaidSearch | 11339 |
| SWE | all | all | 2018-01-07 | Direct | 104596 |
| SWE | all | all | 2018-01-07 | Display | 1108 |
| SWE | all | all | 2018-01-07 | Email | 10130 |
| SWE | all | all | 2018-01-07 | GenericPaidSearch | 7518 |
| SWE | all | all | 2018-01-07 | OrganicSearch | 88386 |
* **Wide Format** (Useful for spreadsheets): Columns represent different channels, with rows as dates. The first few rows define fixed attributes (e.g., Country, Region).
| Country | SWE | SWE | SWE | SWE | SWE |
| ---------- | ----------------- | ------ | ------- | ----- | ----------------- |
| Region | all | all | all | all | all |
| Channel | BrandedPaidSearch | Direct | Display | Email | GenericPaidSearch |
| Grouping | all | all | all | all | all |
| 2018-01-08 | 11339 | 104596 | 1108 | 10130 | 7518 |
| 2018-01-15 | 12064 | 101443 | 651 | 8426 | 9849 |
| 2018-01-22 | 14984 | 148089 | 703 | 8705 | 13072 |
| 2018-01-29 | 14540 | 146961 | 648 | 9620 | 11480 |
| 2018-02-05 | 14967 | 157759 | 719 | 7912 | 10887 |
| 2018-02-12 | 15789 | 158599 | 839 | 6949 | 12334 |
## Best Practices [#best-practices]
* **Consistency:** Ensure dates align with your project's periodicity (e.g., daily visits if the project is set to daily granularity). Mismatched granularity will cause upload errors.
* **Data Quality:** Check for outliers, missing values, or inconsistencies before upload. Use the [Activities](../../Activities) dashboard to visualize and validate post-upload.
* **Granularity Alignment:** All data in a project must match the chosen periodicity (set during project creation). For details, see [Projects](../../Projects).
* **Channel Tracking:** Use clear, consistent channel names to enable segmentation. Align with media or sales channels for cross-analysis.
For uploading instructions, see [Upload Data](../Uploads). If you encounter issues, contact support or refer to the [API](../../API) for programmatic uploads.
# Weather
Weather data includes meteorological indicators that may influence consumer behavior or business operations, such as precipitation, wind speed, temperature, snow, humidity, or sunshine hours. These factors can affect demand in weather-sensitive industries (e.g., precipitation impacting outdoor retail sales or wind affecting energy consumption).
Often sourced from public APIs (e.g., OpenWeatherMap, national meteorological services) or third-party providers, this data allows Alviss AI to model environmental impacts on KPIs like sales or visits. For instance, it can quantify how heavy rain reduces foot traffic, helping to isolate seasonal or climatic effects in attributions, simulations, predictions, and optimizations. By incorporating weather, models can adjust for external variables, improving accuracy in forecasting and strategy planning.
## Data Requirements [#data-requirements]
The Weather Data file must include the following columns (headers). All columns are required unless marked as optional:
* **[Country](../Format/Country)** (string, required): A three-letter country code per ISO 3166 standard (e.g., "UKR" for Ukraine), indicating where the indicators were collected.
* **[Region](../Format/Region)** (string, optional, defaults to "all"): The region within the country (e.g., "all" for nationwide or a specific ISO 3166-2 code).
* **[Grouping](../Format/Grouping)** (string, optional, defaults to "all"): For additional segmentation, such as product categories, demographics, or sales territories.
* **[Date](../Format/Date)** (date, required): The collection date in ISO 8601 format (YYYY-MM-DD).
* **Indicator** (string, required): The name of the weather indicator (e.g., "Precipitation", "Wind", "Snow", "Temperature").
* **Value** (float, required): The value of the indicator (e.g., 2.0 for mm of precipitation). Use consistent units (e.g., mm for rain, m/s for wind; specify in metadata if needed).
Only the following characters are allowed when enter text values: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
## Supported Formats [#supported-formats]
Data can be uploaded in **long** (tidy) or **wide** (pivoted) format. Choose based on your data pipeline:
* **Long Format** (Recommended for flexibility): Each row represents a single observation (one indicator per date, etc.).
| Country | Region | Grouping | Date | Indicator | Value |
| ------- | ------ | -------- | ---------- | ------------- | ----- |
| UKR | all | all | 2018-01-08 | Precipitation | 2.0 |
| UKR | all | all | 2018-01-08 | Wind | 5.0 |
* **Wide Format** (Useful for spreadsheets): Columns represent different indicators, with rows as dates. The first few rows define fixed attributes (e.g., Country, Region).
| Indicator | Precipitation | Snow | Wind |
| ---------- | ------------- | ---------------- | ---------------- |
| Country | UKR | UKR | UKR |
| Region | all | all | all |
| Grouping | all | all | all |
| 2018-01-08 | 0 | 106.666666666667 | 13.1447510822511 |
| 2018-01-15 | 0 | 106.666666666667 | 14.4738149350649 |
| 2018-01-22 | 0 | 106.666666666667 | 14.4211539824263 |
| 2018-01-29 | 0 | 80.7619047619048 | 17.2199343845725 |
| 2018-02-05 | 0 | 78.6190476190476 | 13.2963373712058 |
## Best Practices [#best-practices]
* **Consistency:** Ensure dates align with your project's periodicity (e.g., daily weather if the project is set to daily granularity). Mismatched granularity will cause upload errors.
* **Data Quality:** Source from reliable providers and check for anomalies (e.g., extreme values). Use the [Activities](../../Activities) dashboard to visualize and validate post-upload.
* **Granularity Alignment:** All data in a project must match the chosen periodicity (set during project creation). For details, see [Projects](../../Projects).
* **Indicator Selection:** Choose relevant indicators based on your business. Use clear, consistent naming for easy model integration.
For uploading instructions, see [Upload Data](../Uploads). If you encounter issues, contact support or refer to the [API](../../API) for programmatic uploads.
# Files
Data is uploaded in a couple of different files, each formatted according to the data specification. These files represent various aspects of your business, market, and external factors, enabling comprehensive modeling in Alviss AI. Below is a list of supported data types, with short descriptions and links to their detailed documentation:
* [Sales](../Files/Sales.md): Core dataset tracking units sold, price per unit, and optionally profit per unit to model business outcomes like revenue and demand.
* [Brand](./Brand.md): Metrics on your brand's market perception, such as awareness, liking, penetration, and customer experience tracking.
* [Competitor Brand](./Competitor%20Brand.md): Similar perception metrics for competitors' brands to analyze market dynamics and competitive effects.
* [Distribution](./Distribution.md): Metrics on your distribution network, like number of stores, sales agents, or offices, to model operational presence.
* [Competitor Distribution](./Competitor%20Distribution.md): Distribution metrics for competitors to understand their market reach and impact on your performance.
* [Media](./Media.md): Investments and metrics (e.g., impressions, clicks) for your advertising campaigns across channels like display or Google.
* [Competitor Media](./Competitor%20Media.md): Media investments by competitors to model competitive advertising pressure.
* [Competitor Price](./Competitor%20Price.md): Pricing data for competitors' products to assess price elasticity and market competition.
* [Customer Experience](./Customer%20Experience.md): Investments in CX improvements (e.g., IT, human resources) to estimate ROI on customer satisfaction efforts.
* [Events](./Events.md): Time-bound occurrences like outages or strikes to account for disruptions in modeling.
* [Extra](./Extra.md): Custom variables that don't fit other categories, for flexible inclusion of unique business metrics.
* [Macro](./Macro.md): Macroeconomic indicators like unemployment or consumer confidence to capture broader economic influences.
* [Visits](./Visits.md): Traffic metrics to websites or stores from channels like direct or paid search, to link engagement to conversions.
* [Weather](./Weather.md): Meteorological data like precipitation or wind to model environmental impacts on weather-sensitive operations.
# Country
The Country field identifies the country associated with data entries using a three-letter uppercase code from the ISO 3166-1 alpha-3 standard. This international standard, maintained by the International Organization for Standardization (ISO), ensures consistency, accuracy, and interoperability across global datasets. ISO 3166-1 covers 249 entities, including sovereign states, dependent territories, and special areas.
Using standardized codes prevents ambiguities (e.g., distinguishing between multiple countries with similar names) and facilitates integration with other systems. The Region field, detailed in [Region](../Format/Region), uses ISO 3166-2 for subdivisions and can be "all" if the data is nationwide or not region-specific.
## Data Requirements [#data-requirements]
* **Type:** String (exactly three uppercase letters).
* **Standard:** ISO 3166-1 alpha-3 (three-letter codes).
* **Validation:** Codes must match the official ISO list. Invalid or non-standard codes (e.g., two-letter alpha-2) will cause upload errors.
For Region:
* Use ISO 3166-2 codes (e.g., "US-CA" for California in the USA).
* If not applicable, use "all" or leave blank (Alviss AI treats "all" as nationwide).
## Examples [#examples]
* "USA": United States of America
* "GBR": United Kingdom of Great Britain and Northern Ireland
* "SWE": Sweden
* "AFG": Afghanistan
* "DZA": Algeria
For a full list, refer to the [Wikipedia List of ISO 3166 Country Codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) or the official ISO website.
## Best Practices [#best-practices]
* **Case Sensitivity:** Always use uppercase (e.g., "USA", not "usa").
* **Validation:** Cross-check codes against reliable sources before upload to avoid errors. Use tools like Python's `pycountry` library for automation.
* **Consistency:** Apply the same code uniformly across all files in a project. For multi-country data, segment by Country to enable filtering in dashboards like [Effect](../../Effect).
* **Nationwide Data:** Pair with Region "all" for aggregated national metrics.
* **Updates:** ISO codes rarely change, but monitor for revisions (e.g., new territories) if your data spans long periods.
## Common Issues and Troubleshooting [#common-issues-and-troubleshooting]
* **Invalid Codes:** Using alpha-2 (e.g., "US" instead of "USA") or non-standard abbreviations will fail validation—correct to alpha-3.
* **Length Errors:** Must be exactly three letters; shorter/longer entries are rejected.
* **Deprecated Codes:** Avoid obsolete codes from ISO 3166-3 (e.g., for former countries); use current ones.
For related fields, see [Region](../Format/Region) or [Grouping](../Format/Grouping). If you need the latest ISO list, consult official sources, as standards evolve minimally over time.
# Date
## Overview [#overview]
The Date field in all data files must follow the ISO 8601 standard, an international format for representing dates and times. This ensures consistency, compatibility, and accurate temporal alignment across datasets in Alviss AI.
ISO 8601 supports dates alone or combined with times and time zones, providing flexibility for different granularities. Always use this format to avoid upload errors or model inaccuracies.
## Format Requirements [#format-requirements]
* **Basic Date:** Expressed as `YYYY-MM-DD`, where:
* `YYYY` is the four-digit year.
* `MM` is the two-digit month (01-12, with leading zero).
* `DD` is the two-digit day (01-31, with leading zero).
* **With Time:** Append `T` followed by `HH:MM:SS`, where:
* `HH` is the 24-hour format hour (00-23).
* `MM` is the minute (00-59).
* `SS` is the second (00-59).
* **With Time Zone:** Append `±HH:MM` after the time, where:
* `±` indicates offset from UTC (plus for ahead, minus for behind).
* `HH:MM` is the offset in hours and minutes (e.g., +00:00 for UTC).
Use the start of the period for aggregated data (e.g., Monday for weekly). For details, see [Periodicity](../Format/Periodicity).
## Examples [#examples]
Valid ISO 8601 formats include:
* `2023-04-02` (date without time)
* `2023-04-02T15:30:00` (date with time)
* `2023-04-02T15:30:00-05:00` (date with time and time zone offset)
* `2023-04-02T15:30:00+02:00` (date with time and time zone offset)
## Best Practices [#best-practices]
* **Consistency:** Use the same level of detail (e.g., date-only or with time) across all files in a project. Align with the project's [Periodicity](../Format/Periodicity) to ensure dates match interval starts.
* **Time Zones:** Include offsets if data spans regions; default to UTC if unknown to avoid assumptions.
* **Data Preparation:** Convert non-ISO formats (e.g., MM/DD/YYYY) externally before upload. Tools like Python's `datetime` module can help.
* **Edge Cases:** For periods like quarters or years, use the first day (e.g., `2023-01-01` for Q1). Handle leap years and invalid dates (e.g., no February 30) to prevent errors.
* **Validation:** After upload, check dates in the [Activities](../../Activities) dashboard for alignment and completeness.
See the [Periodicity](../Format/Periodicity) page for details on which dates to use depending on the project's periodicity.
Short summary of rules: Dates must be the first day of the period—e.g., Monday for weekly, 1st for monthly, 1st of starting month for quarterly (January 1 for Q1), January 1 for yearly. Always follow ISO 8601 for weeks (starting Monday).
## Common Issues and Troubleshooting [#common-issues-and-troubleshooting]
* **Invalid Formats:** Non-ISO dates (e.g., `04-02-2023`) will cause upload failures—reformat to `YYYY-MM-DD`.
* **Missing Leading Zeros:** Use `2023-01-01`, not `2023-1-1`.
* **Time Zone Mismatches:** Inconsistent offsets can skew time-series; standardize to one zone.
* **Period Mismatch:** Dates not on period starts (e.g., weekly on Friday) violate [Periodicity](../Format/Periodicity)—adjust accordingly.
For related topics, see [Periodicity](../Format/Periodicity) or [Upload Data](../Uploads). If issues arise, contact support.
# File Format
Files uploaded to Alviss AI must adhere to a standardized format to ensure successful ingestion, validation, and processing. Supported formats include CSV and Excel (.xlsx), with specific rules for separators, decimals, and structure. This consistency prevents parsing errors and maintains data integrity across sources, enabling seamless dataset creation, modeling, and analysis.
Proper formatting is critical during [Upload Data](../Uploads), as inconsistencies can lead to immediate notifications or failures. Always prepare files externally (e.g., via Excel, Python's pandas) to match these specifications.
## Supported Formats [#supported-formats]
* **CSV (Comma-Separated Values):** Plain text files with comma-separated fields.
Excel may default to semicolons (;) or tabs in some regions—explicitly select comma when saving as CSV.
* **Excel:** .xlsx (standard Excel format).
In Excel, dates may auto-format based on your locale (e.g., MM/DD/YYYY vs. DD/MM/YYYY). Always export as text or force ISO 8601 (YYYY-MM-DD) to avoid corruption.
## Data Requirements [#data-requirements]
* **Separator (CSV Only):** Must use a comma (`,`) as the field delimiter.
* **Decimal Separator:** Use a period (`.`) for decimal numbers (e.g., 3.14, not 3,14).
* **Row Structure:** Each row represents a single record or observation.
* **Headers:** The first row must contain column names (headers) exactly matching the required fields for the data type (e.g., "Country", "Date").
* **Field Order:** Data in each row must align with the header order—no mismatches or extra/missing columns.
* **Missing Values:** Represent as empty strings (\`\`) or placeholders (e.g., "NaN", "null"); avoid inconsistent representations.
* **Encoding:** Use UTF-8 to handle special characters, accents, or international text correctly.
* **No Formulas or Formatting:** Excel files should contain raw data only—no embedded formulas, conditional formatting, or macros.
## Best Practices [#best-practices]
* **Preparation Tools:** Use spreadsheet software like Excel or Google Sheets for initial setup, then export to CSV or save as .xlsx. For automation, leverage libraries like pandas in Python to enforce formats.
* **File Size:** For large datasets, prefer .xlsx for better handling; split very large files if needed, but ensure consistent headers across parts.
* **Testing:** Upload a small sample file first to verify formatting via platform notifications.
* **International Considerations:** Set your software's locale to US/English for exports to ensure comma separators and period decimals.
* **Text Handling:** Enclose text fields in quotes if they contain commas (e.g., "Product, Name") to prevent splitting in CSV.
* **Date and Numeric Consistency:** Cross-reference with [Date](../Format/Date) and [Periodicity](../Format/Periodicity) for temporal fields.
## Most Common Issues [#most-common-issues]
* **Date Formatting:** In Excel, dates may auto-format based on your locale (e.g., MM/DD/YYYY vs. DD/MM/YYYY). Always export as text or force ISO 8601 (YYYY-MM-DD) to avoid corruption.
* **CSV Separator:** Excel may default to semicolons (;) or tabs in some regions—explicitly select comma when saving as CSV.
* **Thousand Separators:** Avoid them entirely (e.g., use 100000, not 100,000 or 100.000), as they can cause column splits or truncation (e.g., 100,000 becoming two fields, or 100.000 parsed as 100 in some locales).
* **Text Fields with Commas:** Commas in values (e.g., "High-End, Product") can split columns in CSV—enclose in double quotes or replace commas with alternatives like semicolons.
* **Encoding Problems:** Non-UTF-8 files may garble special characters—save explicitly as UTF-8.
* **Header Mismatches:** Typos or order changes in headers will block uploads—double-check against data type specs (e.g., [Sales](../Files/Sales)).
For troubleshooting uploads, see [Upload Data](../Uploads). If persistent issues occur, export to CSV for simplicity and contact support.
# Grouping
## Overview [#overview]
The Grouping field provides a flexible way to categorize or segment data beyond standard geographic dimensions like [Country](../Format/Country) and [Region](../Format/Region). It acts as a placeholder for any natural grouping relevant to your business, such as product lines, customer segments, sales channels, store locations, or custom hierarchies. This allows for more granular analysis, enabling filtering in dashboards like [Effect](../../Effect) and [Activities](../../Activities), and forms part of the [Modeling Combination](../../Models/Modeling%20Combination) for targeted modeling.
Unlike Region, which can benefit from ISO 3166-2 alignment for integrations (e.g., with [Weather](../Files/Weather)), Grouping has no enforced standards, offering complete freedom to tailor it to your operational structure. If no additional segmentation is needed, default to "all" for simplicity.
## Data Requirements [#data-requirements]
* **Type:** String (free text; no restrictions on format, length, or content).
* **Validation:** Only the following characters are allowed: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
For ungrouped or aggregated data:
* Use "all" to indicate no further segmentation.
## Examples [#examples]
* "Product Line A": Grouping by product categories.
* "Enterprise Customers": Segmenting by customer type.
* "Online Channel": Distinguishing sales channels.
* "Store-123": Granular tracking of individual stores or outlets (e.g., as a sub-layer below regions).
* "all": Default for nationwide or unsegmented entries.
* "Holiday Campaign": Custom grouping for seasonal promotions.
Grouping is part of the modeling combination, i.e., individual models will be created for each grouping. So if, e.g., the same Media spend can affect the KPI, it should not be split into the groupings. But one should rather use something like "Product" so it gets included in the same model.
## Best Practices [#best-practices]
* **Business Alignment:** Define groupings based on how your organization structures data (e.g., align with CRM categories or inventory systems) to maximize relevance in modeling and reporting.
* **Consistency:** Use uniform naming across all files (e.g., always "Store-123" instead of varying "Store123" or "Location 123") to enable accurate filtering and aggregation.
* **Granularity:** Leverage for finer detail than regions (e.g., individual stores within a state) or broader custom layers (e.g., "B2B" vs. "B2C"). Combine with Region for hierarchical views.
* **Default Usage:** Stick to "all" if segmentation isn't needed to simplify datasets and reduce complexity.
## Common Issues and Troubleshooting [#common-issues-and-troubleshooting]
* **Inconsistencies:** Variant spellings (e.g., "Prod A" vs. "Product A") can scatter data—standardize during preparation.
* **Over-Segmentation:** Too many unique groupings may dilute insights; consolidate similar ones (e.g., group small stores into "Regional Outlets").
* **Blanks vs. "all":** Blanks may cause optional field issues; prefer "all" for clarity and consistency.
* **Modeling Impacts:** Inconsistent groupings can affect [Modeling Combinations](../../Models/Modeling%20Combination); test small datasets first.
For related fields, see [Country](../Format/Country) or [Region](../Format/Region). If using ISO-like formats for regions, consider extending similar practices here for internal consistency, though it's not required.
# Periodicity
## Overview [#overview]
Data periodicity defines the consistent time interval at which observations are recorded across all data sources in a project. This ensures alignment and coherence for modeling, analysis, and insights in Alviss AI. All datasets within a project must adhere to the same periodicity (e.g., daily, weekly, monthly), which is set during [project creation](../../Projects) and cannot be changed later.
For example, if sales are tracked weekly, every data point (e.g., media investments, brand metrics) must also aggregate to weekly intervals. This prevents mismatches that could lead to inaccurate attributions, simulations, or predictions. The [Date](../Format/Date) field always represents the **first day** of the period, even if the value (e.g., total sales) spans the entire interval.
## Supported Periodicities [#supported-periodicities]
The currently supported periodicity options are:
* Minute
* Hour
* Day
* Week
* Month
* Quarter
* Year
## Key Requirements [#key-requirements]
* **Coherent Intervals:** All data sources must have exactly one observation per period for each unique combination of Country, Region, Product, Grouping, etc. Gaps or duplicates will cause upload errors or model inaccuracies.
* **Date Placement:** The [Date](../Format/Date) must fall on the first day of the period:
* **Minute:** The start of the minute (use timestamp if needed for precision).
* **Hour:** The start of the hour.
* **Day:** The exact date.
* **Week:** Monday (following ISO 8601 standard, where weeks start on Monday).
* **Month:** The 1st day of the month.
* **Quarter:** The 1st day of the starting month (e.g., January 1 for Q1, April 1 for Q2, July 1 for Q3, October 1 for Q4).
* **Year:** January 1.
* **Aggregation:** If raw data is more granular (e.g., daily sales for a weekly project), aggregate values (e.g., sum units sold) and assign to the period's start date.
Alviss AI follows the ISO 8601 standard for weeks (starting on Monday), regardless of local calendar conventions (e.g., Sunday starts in some countries).
## Example: Weekly Periodicity [#example-weekly-periodicity]
Consider ISO Week 32 in 2022, starting Monday, August 8, and ending Sunday, August 14. Total sales for this week would be recorded with the date "2022-08-08" (the first day), even if sales occurred throughout the week.
```
┌────────────────────┐
│ August ▒▒▒▒▒▒ 2022 │
├──┬──┬──┬──┬──┬──┬──┤
│Su│Mo│Tu│We│Th│Fr│Sa│
├──┼──┼──┼──┼──┼──┼──┤
│▒▒│01│02│03│04│05│06│
├──╔══╗──┼──┼──┼──┼──┤
│07║08║09│10│11│12│13│ <--- Week 32 starts here (Monday, August 8)
├──╚══╝──┼──┼──┼──┼──┤
│14│15│16│17│18│19│20│
├──┼──┼──┼──┼──┼──┼──┤
│21│22│23│24│25│26│27│
├──┼──┼──┼──┼──┼──┼──┤
│28│29│30│31│▒▒│▒▒│▒▒│
└──┴──┴──┴──┴──┴──┴──┘
```
In a [Sales](../Files/Sales) file for this week:
* Date: 2022-08-08
* Value: Sum of units sold from August 8–14
This approach applies to all data types, ensuring the date references the full period.
## Best Practices [#best-practices]
* **Choose Periodicity Wisely:** Select based on your data availability and business needs (e.g., weekly for fast-moving consumer goods, monthly for B2B). Finer granularity (e.g., daily) provides more detail but requires more data.
* **Data Preparation:** Aggregate raw data externally (e.g., using tools like Python's pandas) to match the project's periodicity before upload.
* **Consistency Across Sources:** Align all files (e.g., [Media](../Files/Media) investments, [Weather](../Files/Weather) averages, ...) to the same intervals to avoid errors during dataset creation or modeling.
* **Time Zones and Holidays:** Use UTC or consistent local time for dates. Account for holidays or irregular periods in [Events](../Files/Events) if they disrupt standard intervals.
* **Validation:** After upload, review in the [Activities](../../Activities) dashboard for gaps or misalignments. Test with a small dataset to confirm periodicity before full import.
## Common Issues and Troubleshooting [#common-issues-and-troubleshooting]
* **Mismatched Dates:** If dates don't align with period starts (e.g., weekly on Tuesday), uploads will fail. Adjust externally to the first day.
* **Gaps in Data:** Missing periods can bias models, missing data will be interpolated and extrapolated according to the [Interpolation and Extrapolation](../Interpolation%20and%20Extrapolation) rules.
* **Granularity Mismatch:** Uploading daily data to a weekly project will error; aggregate first.
* **ISO Week Conflicts:** If your local week starts on Sunday, remap dates to ISO Mondays to comply.
For more on date formatting, see [Date](../Format/Date). If issues persist during upload, refer to [Upload Data](../Uploads) or contact support.
# Region
## Overview [#overview]
The Region field specifies subdivisions or areas within a country where your business operates or collects data. These can be geographically defined (e.g., states, provinces) or internally structured regions (e.g., sales territories, business units). Regions enable granular analysis, allowing filtering in dashboards like [Effect](../../Effect) and [Activities](../../Activities), and form part of the [Modeling Combination](../../Models/Modeling%20Combination) for segmented modeling.
Unlike the strict ISO standards for [Country](../Format/Country.md), regions offer flexibility to align with your business needs. This supports custom hierarchies while maintaining data integrity for geographic-specific insights, such as regional performance trends or localized optimizations.
## Data Requirements [#data-requirements]
* **Type:** String (free text; no major restrictions on format or length).
* **Required:** In most data files (e.g., [Sales](../Files/Sales), [Media](../Files/Media)) for geographic segmentation; optional if nationwide (use "all" or blank).
* **Validation:** Only the following characters are allowed: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`
For non-applicable or nationwide data:
* Use "all" to indicate aggregated scope.
## Examples [#examples]
* "North America East": Custom business region.
* "California": Free-text geographic name.
* "US-CA": ISO 3166-2 format for California, USA (optional, but recommended for integrations).
* "Sales District 1": Internal territory.
* "all": Nationwide or non-segmented.
If you enter regions following a similar practice to [Country](../Format/Country) using the ISO 3166-2 standard ([Wikipedia contributors 2022c](https://en.wikipedia.org/wiki/ISO_3166-2)), and incorporate [Weather](../Files/Weather.md) as an external data source, you can access weather data specific to that region for enhanced environmental modeling.
## Best Practices [#best-practices]
* **Flexibility with Structure:** Define regions based on your operations (e.g., mix geographic and custom). Keep names consistent (e.g., always "US-CA" or "California") to avoid duplication.
* **Validation and Consistency:** While free text is allowed, use tools or scripts to standardize entries before upload. Align with business hierarchies for meaningful [Filtering](../../Filtering).
* **Integration Benefits:** Opt for ISO 3166-2 (e.g., "SE-AB" for Stockholm County, Sweden) when possible, especially for [Weather](../Files/Weather.md) or external data linkages, to unlock automated features.
* **Nationwide Data:** Default to "all" for simplicity; avoid blanks to prevent parsing issues.
## Common Issues and Troubleshooting [#common-issues-and-troubleshooting]
* **Inconsistencies:** Mismatched spellings (e.g., "Calif" vs. "California") can fragment data—standardize upfront.
* **No Restrictions Leading to Errors:** Overly complex names may cause display issues in dashboards; keep concise.
* **ISO Integration:** If using ISO for weather but free text elsewhere, map them during data prep to avoid conflicts.
For related fields, see [Country](../Format/Country) or [Grouping](../Format/Grouping). For the ISO 3166-2 list, consult [Wikipedia](https://en.wikipedia.org/wiki/ISO_3166-2) or official ISO sources.
# Advanced Model Builder
The Advanced Model Builder is tailored for experienced users who require precise control over model architecture to capture complex dynamics, interactions, and business-specific behaviors. Unlike the \[Basic Model Builder]\(../Basic Model Builder.md), this tool allows you to construct models from the ground up using Alviss AI's intuitive graphical interface, incorporating advanced statistical distributions, custom transformations, and hierarchical structures.
This builder leverages Bayesian modeling principles to enable flexible prior specifications, effect directions, and variable interactions, making it ideal for scenarios where default assumptions may not suffice—such as modeling non-linear effects, synergies between marketing channels, or external economic factors.
#### Steps to Build a Model [#steps-to-build-a-model]
1. **Select Dataset**\
Choose the [Dataset](../../Data/Datasets.md) that will form the basis of your model. Ensure it aligns with your project's [periodicity](../../Data/Format/Periodicity) and has been inspected for quality in the [Activities](../../Activities) dashboard.
2. **Choose Modeling Combinations**\
Specify the \[modeling combinations]\(../Modeling Combination.md) (e.g., unique blends of Country, Region, and Grouping). Alviss AI will generate a dedicated model for each selected combination, allowing for targeted analysis across data segments.
3. **Build Your Model Structure Using the Graph Editor**\
At the core of the Advanced Model Builder is the Graph Editor, a visual tool where models are represented as directed acyclic graphs (DAGs). Here, **nodes** (rectangular boxes) encapsulate variables, probabilistic distributions, or mathematical operations, while **edges** (connecting lines) define the directional flow of information and dependencies.
* **Nodes:**\
Drag nodes from the left sidebar into the central canvas to incorporate them into your model. Each node performs a distinct function, such as representing a data variable (e.g., sales or ad spend), applying a transformation (e.g., adstock for carryover effects), or defining a distribution (e.g., Normal or Poisson for likelihoods).
* **Configure a Node:** Select a node to access its configuration panel on the right. Here, you can fine-tune parameters like prior distributions, effect constraints, or scaling factors to embed domain expertise—such as setting a positive prior for marketing ROI or incorporating seasonality.\
* **Edges:**\
Connect nodes by dragging from an output port (on the right of a node) to an input port (on the left of another). Edges not only link components but can also carry attributes that specify relationships, enhancing model expressiveness:
* Define the directional impact of a variable on a KPI (e.g., positive, negative, or unconstrained).\
* Specify the role of the source node in the target (e.g., as a multiplier, divisor, or additive term in operations like summation or division).\
* **Insert Basic Graph:**\
Kickstart your custom model by inserting a pre-configured "Basic Graph," which mirrors the structure of a model created via the \[Basic Model Builder]\(../Basic Model Builder.md). This provides a solid foundation that you can then modify—adjusting nodes, reconfiguring edges, or adding new elements to suit your needs.
Starting with the **Insert Basic Graph** option is highly recommended for efficiency. It automates the initial setup, allowing you to focus on refinements rather than building entirely from scratch.
4. **Advanced Settings (Optional)**\
Customize training parameters such as the number of samples, learning rate, epochs, and date ranges for training/hold-out periods. Enable automatic post-training actions like generating [Predictions](../../Predictions), [Attributions](../../Attributions), or activating the model as the \[active model]\(../Active Model.md).
Validate your graph structure before training: Ensure there are no cycles, all required inputs are connected, and the model aligns with your business logic. Use tooltips in the editor for guidance on node/edge options, and test with a small dataset subset to iterate quickly.
Once your model is configured and submitted, Alviss AI will train it in the background using Bayesian inference for robust uncertainty quantification. Upon completion, review performance metrics, activate the model for use in dashboards, or refine further.
# Graph Editor
The Graph Editor is the visual interface at the heart of the \[Advanced Model Builder]\(../Advanced Model Builder), enabling you to construct, modify, and refine model structures through an intuitive drag-and-drop system. Representing models as directed graphs, it allows for precise definition of variables, transformations, distributions, and relationships—empowering advanced users to embed domain knowledge and capture complex business dynamics.
To maximize efficiency in the Graph Editor, familiarize yourself with these practical tips and features. They streamline workflows, from node configuration to bulk operations, making it easier to build sophisticated models for tasks like attribution analysis, simulations, and optimizations.
## Side Menu Configuration [#side-menu-configuration]
When you left-click on a node or edge in the graph, a contextual menu opens on the right side of the editor. This menu displays detailed information about the selected element and provides options to update its configuration, such as adjusting parameters, priors, or attributes.
This feature allows for quick, targeted edits without disrupting your overall graph layout.
***
## Right-Click Menu [#right-click-menu]
Right-clicking on a node or a group of nodes summons a contextual menu with specialized actions, such as deleting, duplicating, or grouping elements. This menu adapts based on the selected item(s), offering relevant tools to manage your model structure efficiently.
Use this for rapid operations on individual components or selections.
***
## Proximity Connect [#proximity-connect]
Drag a node near another to preview a temporary edge connection. If you release the node in close proximity (and no existing connection is present), the editor automatically creates the edge. This simplifies building relationships between nodes.
To disable this auto-connect behavior temporarily, hold the `Shift` key while dragging.
Proximity Connect is great for initial graph sketching but can be toggled off during precise rearrangements to avoid unintended links.
***
## Select Multiple Nodes [#select-multiple-nodes]
Multi-selection enables batch operations like moving, cloning, or connecting groups of nodes. There are two methods:
* Hold `Shift`, then left-click and drag a selection box over the desired nodes.\
* Hold `Ctrl` (or \`\` on macOS), then left-click individual nodes one by one.\
Once selected, you can perform actions on the entire group, enhancing productivity for complex models.
***
## Multiple Connections [#multiple-connections]
With two or more nodes selected, creating a connection from one selected node to a target will automatically replicate that connection from all other selected nodes to the same target. This is ideal for applying uniform relationships across similar components.
This feature saves time when modeling symmetric or hierarchical structures, such as multiple media channels feeding into a summation node.
***
## Reconnect Edge [#reconnect-edge]
Edges can be dynamically reassigned by left-clicking and dragging the segment near a handle (watch for the cursor change). Release on a new input/output port to reconnect. The editor attempts to preserve any existing edge attributes, like directional impact or functional roles.
This flexibility allows for iterative refinements without recreating edges from scratch.
***
## Clone by Dragging [#clone-by-dragging]
To duplicate a node (or group), hold `Alt` while dragging it. A temporary copy appears with its connections intact; release to make it permanent.
To cancel, release `Alt` before dropping the node.\
This works with multi-selections too:\
For connection-free clones, hold `Alt` + `Shift` while dragging.\
Cloning is particularly useful for experimenting with variations or scaling subgraphs.
***
## Select Multiple Edges [#select-multiple-edges]
Unlike nodes, edges are selected individually: Hold `Ctrl` (or \`\` on macOS), then left-click each edge one by one.
This prepares edges for bulk actions, ensuring precise control over connections.
***
## Edges Bulk Actions [#edges-bulk-actions]
Selecting two or more edges opens the "Multiple Edges" menu on the right, enabling batch operations:
* **Bulk Update Arguments:** Modify attributes (e.g., impact direction) across all selected edges simultaneously. This only applies if the edges share the same type.\
* **Bulk Delete:** Remove all selected edges at once, or simply press the `Delete` key.\
These actions accelerate maintenance of large graphs, especially when refining models based on new insights from [datasets](../../Data/Datasets) or performance reviews.
Always validate your graph after bulk changes to ensure model integrity—check for disconnected nodes or invalid flows using the editor's built-in validation tools.
***
## Import - Export [#import---export]
For greater flexibility and collaboration, you can import and export your graph structures as JSON files. This allows you to save models externally, share them with team members, or integrate with version control systems. To access these options, use the dedicated buttons in the Graph Editor toolbar.
* **Export:** Download the current graph as a JSON file, capturing all nodes, edges, configurations, and attributes.
* **Import:** Upload a previously exported JSON file to load a graph into the editor, restoring the structure for further editing or training.
When exporting, include a descriptive filename (e.g., "Media\_Optimization\_Model\_v1.json") to track versions. For imports, ensure the JSON aligns with your current dataset variables to avoid mapping issues.
Imported graphs may require reconfiguration if variable names or project settings differ. Always review and validate after import before proceeding to training.
# Templates
To streamline the model-building process in the \[Advanced Model Builder]\(../Advanced Model Builder), Alviss AI offers a selection of pre-configured templates. These templates serve as ready-made starting points, allowing you to quickly insert proven graph structures into your model and customize them as needed. This feature accelerates development, reduces setup time, and ensures consistency across projects while incorporating best practices for common business scenarios.
You can access templates via the **Insert Template** option in the Graph Editor. Select from standard or user-defined templates to populate your canvas automatically.
## Standard Templates [#standard-templates]
Alviss AI includes several built-in templates designed for frequent use cases in holistic business measurement and optimization. Each template inserts a subgraph or full model structure that you can modify to fit your data and objectives.
* **Basic Model:**\
Inserts the same foundational graph as generated by the \[Basic Model Builder]\(../Basic Model Builder.md). This serves as an excellent starting point for customizations, providing a simple yet robust structure for quantifying the impact of key drivers on KPIs like sales or churn.
* **Event:**\
Adds nodes to incorporate events into your model, either by linking to event variables in your [dataset](../../Data/Datasets.md) or by manually specifying dates. Ideal for modeling the effects of one-time occurrences, such as promotions, holidays, or external disruptions.
* **Media:**\
Inserts a subgraph to handle media dynamics, including transformations like adstock for carryover effects and saturation curves for diminishing returns. This template is particularly useful for optimizing marketing investments across channels.
* **Price Variation:**\
Captures customer responses to recent price changes by adding nodes for elasticity and behavioral shifts. Helps in analyzing how pricing strategies influence demand, churn, or revenue in dynamic markets.
* **GLM (Generalized Linear Model):**\
Constructs a flexible generalized linear model with granular control over distributions, links, and parameters. This is especially valuable for importing or replicating models from other frameworks, ensuring compatibility while leveraging Alviss AI's Bayesian capabilities for uncertainty quantification.
Start with a standard template that closely matches your use case, then use the Graph Editor to add or adjust nodes and edges. This approach combines efficiency with the flexibility needed for tailored insights.
## User Templates [#user-templates]
For even greater customization, team members can create and share their own templates. These are stored at the team level, making them accessible across all [projects](../../Projects) within the [team](../../Teams). This promotes collaboration and standardization of modeling practices.
### Creating a User Template [#creating-a-user-template]
1. Build or modify a graph in the Advanced Model Builder's Graph Editor to represent the desired structure.
2. Once complete, click **Create a New Template** to save it.
3. Provide a name and optional description for easy identification.
### Using a User Template [#using-a-user-template]
* In the Graph Editor, select **Insert Template > User Template**.
* Choose from the list of available team templates to insert the graph into your current model.
When saving a template, avoid pre-selecting specific data variables in the graph nodes. If variables are already assigned, they will attempt to map to the exact same names in future projects—even if those variables do not exist. In such cases, you will need to manually unselect and reselect appropriate variables from the current [dataset](../../Data/Datasets.md). For best results, keep templates variable-agnostic to ensure seamless reuse.
# Tutorials
Learn how to use the Alviss AI platform using tutorials.
# Create A New Model Based On An Existing Model
This tutorial covers creating a new model in Alviss AI based on an existing model (a "remodel" process), training it from scratch with possibly different modeling assumptions, rather than just updating via refit. It demonstrates using both high-level and low-level graphs from the existing model. This is useful for experimenting with new configurations while leveraging existing model structures. We'll walk through the process step by step using Python with the `requests` library to interact with the Alviss AI API. For each step, the relevant valid Python code snippet is provided.
Note: Unlike refitting, this script does not include polling for completion, assuming the operations are synchronous or that status checks can be added if needed based on your workflow.
### Prerequisites [#prerequisites]
* You need a valid access token from the Alviss AI platform (see the Authentication section in the main API docs).
* Know your team ID, project ID, and the target model ID to base the new model on.
* Ensure the existing model has associated dataset and graph information accessible.
* Install the required Python libraries if not already present: `pip install requests` (though it's standard).
### Step 1: Import Necessary Libraries [#step-1-import-necessary-libraries]
Import `requests` for making HTTP API calls.
```python
import requests
```
### Step 2: Set Up Variables [#step-2-set-up-variables]
Define the base API URL, your access token, team ID, project ID, and the target model ID. Replace placeholders like `` with actual values.
```python
url = "https://app.alviss.io/api/v1/api"
token = ""
team_id = ""
project_id = ""
target_model_id = 11
```
### Step 3: Prepare Authentication Headers [#step-3-prepare-authentication-headers]
Create a headers dictionary with the Authorization Bearer token to authenticate all API requests.
```python
headers = {"Authorization": "Bearer " + token}
```
### Step 4: Construct the Project URL [#step-4-construct-the-project-url]
Build the base URL for the team and project-specific endpoints by formatting the team ID and project ID into the URL string.
```python
team_project_url = url + f"/projects/{team_id}/{project_id}"
```
### Step 5: Retrieve Existing Model Information [#step-5-retrieve-existing-model-information]
Send a GET request to the `/models/{target_model_id}` endpoint to fetch details about the existing model. Extract the high-level graph ID and dataset ID from the response.
```python
response = requests.get(
team_project_url + f"/models/{target_model_id}",
headers=headers,
)
model_info = response.json()
high_level_graph_id = model_info["GraphInstance"]["Graph"]["Id"]
dataset_id = model_info["DataSet"]["IId"]
```
### Step 6: Retrieve High-Level Graph [#step-6-retrieve-high-level-graph]
Send a GET request to the `/build/graphs/{high_level_graph_id}` endpoint to fetch the high-level graph structure (nodes and edges).
```python
response = requests.get(
team_project_url + f"/build/graphs/{high_level_graph_id}",
headers=headers,
)
high_level_graph = response.json()
```
### Step 7: Retrieve Dataset Dates [#step-7-retrieve-dataset-dates]
Send a POST request to the `/datasets/{dataset_id}/dates` endpoint with the dataset name as a parameter and model-specific filters (country, region, grouping from the existing model info) in the JSON payload. This returns a list of `data_dates`.
```python
response = requests.post(
team_project_url + f"/datasets/{dataset_id}/dates",
headers=headers,
params={"dataset_name": "Sales"},
json=[
{
"country_code": model_info["Country"],
"region_code": model_info["Region"],
"grouping": model_info["Grouping"],
}
],
)
data_dates = response.json()
```
### Step 8: Split Dates for Training and Evaluation [#step-8-split-dates-for-training-and-evaluation]
Calculate a separator index at 75% of the data dates length, then slice the list to create `train_dates` and `eval_dates` for the new model.
```python
separator_date = int(len(data_dates) * 0.75)
train_dates = data_dates[:separator_date]
eval_dates = data_dates[separator_date:]
```
### Step 9: Submit New Model Using High-Level Graph [#step-9-submit-new-model-using-high-level-graph]
Send a POST request to the `/build/model` endpoint with model parameters, details (including dataset, dates, activation flag, and modeling combination), and the high-level graph in the JSON payload. This creates and submits the new model.
```python
response = requests.post(
team_project_url + "/build/model",
headers=headers,
json={
"model_param": {
"epochs": 50,
"learning_rate": 0.01,
"samples": 2,
},
"model_detail": {
"dataset_id": dataset_id,
"train_dates": train_dates,
"eval_dates": eval_dates,
"activate": False, # auto activate
"modelling_combination": {
"country_code": model_info["Country"],
"region_code": model_info["Region"],
"grouping": model_info["Grouping"],
},
},
"graph_detail": {
"graph": {
"nodes": high_level_graph["nodes"],
"edges": high_level_graph["edges"],
}
},
},
)
```
### Step 10: Retrieve Low-Level Graph ID [#step-10-retrieve-low-level-graph-id]
Extract the low-level graph ID from the existing model info.
```python
low_level_graph_id = model_info["GraphInstance"]["Id"]
```
### Step 11: Retrieve Low-Level Graph [#step-11-retrieve-low-level-graph]
Send a GET request to the `/graph_instances/{team_id}/{low_level_graph_id}` endpoint to fetch the low-level graph structure (nodes and edges). Note: This uses the base `url`, not the team\_project\_url.
```python
response = requests.get(
url + f"/graph_instances/{team_id}/{low_level_graph_id}",
headers=headers,
)
low_level_graph = response.json()
```
### Step 12: Submit New Model Using Low-Level Graph [#step-12-submit-new-model-using-low-level-graph]
Send a POST request to the `/build/model` endpoint with similar model parameters and details, but using the low-level graph in the JSON payload. This creates another new model variant.
```python
response = requests.post(
team_project_url + "/build/model",
headers=headers,
json={
"model_param": {
"epochs": 50,
"learning_rate": 0.01,
"samples": 2,
},
"model_detail": {
"dataset_id": dataset_id,
"train_dates": train_dates,
"eval_dates": eval_dates,
"activate": False, # auto activate
"modelling_combination": {
"country_code": model_info["Country"],
"region_code": model_info["Region"],
"grouping": model_info["Grouping"],
},
},
"graph_detail": {
"graph": {
"nodes": low_level_graph["nodes"],
"edges": low_level_graph["edges"],
}
},
},
)
```
### Full Example Code [#full-example-code]
```python
import requests
url = "https://app.alviss.io/api/v1/api"
token = ""
team_id = ""
project_id = ""
headers = {"Authorization": "Bearer " + token}
team_project_url = url + f"/projects/{team_id}/{project_id}"
target_model_id = 11
response = requests.get(
team_project_url + f"/models/{target_model_id}",
headers=headers,
)
model_info = response.json()
high_level_graph_id = model_info["GraphInstance"]["Graph"]["Id"]
dataset_id = model_info["DataSet"]["IId"]
response = requests.get(
team_project_url + f"/build/graphs/{high_level_graph_id}",
headers=headers,
)
high_level_graph = response.json()
response = requests.post(
team_project_url + f"/datasets/{dataset_id}/dates",
headers=headers,
params={"dataset_name": "Sales"},
json=[
{
"country_code": model_info["Country"],
"region_code": model_info["Region"],
"grouping": model_info["Grouping"],
}
],
)
data_dates = response.json()
separator_date = int(len(data_dates) * 0.75)
train_dates = data_dates[:separator_date]
eval_dates = data_dates[separator_date:]
# submit the model using high level graph
response = requests.post(
team_project_url + "/build/model",
headers=headers,
json={
"model_param": {
"epochs": 50,
"learning_rate": 0.01,
"samples": 2,
},
"model_detail": {
"dataset_id": dataset_id,
"train_dates": train_dates,
"eval_dates": eval_dates,
"activate": False, # auto activate
"modelling_combination": {
"country_code": model_info["Country"],
"region_code": model_info["Region"],
"grouping": model_info["Grouping"],
},
},
"graph_detail": {
"graph": {
"nodes": high_level_graph["nodes"],
"edges": high_level_graph["edges"],
}
},
},
)
# build model with low level graph
low_level_graph_id = model_info["GraphInstance"]["Id"]
response = requests.get(
url + f"/graph_instances/{team_id}/{low_level_graph_id}",
headers=headers,
)
low_level_graph = response.json()
response = requests.post(
team_project_url + "/build/model",
headers=headers,
json={
"model_param": {
"epochs": 50,
"learning_rate": 0.01,
"samples": 2,
},
"model_detail": {
"dataset_id": dataset_id,
"train_dates": train_dates,
"eval_dates": eval_dates,
"activate": False, # auto activate
"modelling_combination": {
"country_code": model_info["Country"],
"region_code": model_info["Region"],
"grouping": model_info["Grouping"],
},
},
"graph_detail": {
"graph": {
"nodes": low_level_graph["nodes"],
"edges": low_level_graph["edges"],
}
},
},
)
```
# Extend Active Attribution Set
This tutorial covers extending the active attribution set in Alviss AI by fetching the current active set, aligning dates with a new attribution ID, creating a new set, polling for completion, and optionally activating it. This is useful for updating attribution sets in ongoing projects to include new attributions while maintaining consistency. We'll walk through the process step by step using Python with the `requests` library to interact with the Alviss AI API. For each step, the relevant valid Python code snippet is provided.
### Prerequisites [#prerequisites]
* You need a valid access token from the Alviss AI platform (see the Authentication section in the main API docs).
* Know your team ID and project ID.
* Have a new attribution ID ready (e.g., from a previous attribution creation step; in the example, it's hardcoded as 5, but replace with your actual ID).
* Install the required Python libraries if not already present: `pip install requests` (though it's standard).
### Step 1: Import Necessary Libraries [#step-1-import-necessary-libraries]
Import `time` for handling delays in polling and `requests` for making HTTP API calls.
```python
import time
import requests
```
### Step 2: Set Up Variables [#step-2-set-up-variables]
Define the base API URL, your access token, team ID, and project ID. Replace placeholders like `` with actual values.
```python
url = "https://app.alviss.io/api/v1/api"
token = ""
team_id = ""
project_id = ""
```
### Step 3: Prepare Authentication Headers [#step-3-prepare-authentication-headers]
Create a headers dictionary with the Authorization Bearer token to authenticate all API requests.
```python
headers = {"Authorization": "Bearer " + token}
```
### Step 4: Construct the Project URL [#step-4-construct-the-project-url]
Build the base URL for the team and project-specific endpoints by formatting the team ID and project ID into the URL string.
```python
team_project_url = url + f"/projects/{team_id}/{project_id}"
```
### Step 5: Get the Active Attribution Set [#step-5-get-the-active-attribution-set]
Send a GET request to the `/attributionset/active` endpoint to retrieve the current active attribution set. Extract the list of existing attribution IDs from the response.
```python
response = requests.get(
team_project_url + "/attributionset/active",
headers=headers,
)
attribution_ids = [_attr["IId"] for _attr in response.json()["Attributions"]]
```
### Step 6: Define the New Attribution ID [#step-6-define-the-new-attribution-id]
Specify the new attribution ID to add to the set. In this example, it's hardcoded as 5; replace with your actual new attribution ID.
```python
attribution_id = 5
```
### Step 7: Create a New Attribution Set by Aligning Dates [#step-7-create-a-new-attribution-set-by-aligning-dates]
Send a POST request to the `/attributionset_align_dates` endpoint with the combined list of attribution job IDs (new and existing) in the JSON payload. Set `"active": False` to not activate immediately (change to True if desired). This returns a new `attribution_set_id`.
```python
response = requests.post(
team_project_url + "/attributionset_align_dates",
headers=headers,
json={
"attributionjob_ids": [attribution_id, *attribution_ids],
"active": False, # set to True if you want to make this attribution set active
},
)
attribution_set_id = response.json().get("IId")
```
### Step 8: Poll for Attribution Set Completion [#step-8-poll-for-attribution-set-completion]
Use a while loop to repeatedly send GET requests to check the status of the new attribution set. Print progress messages and the response for debugging, and sleep for 2 seconds between checks. Break when the status is "complete".
```python
while True:
print("Waiting for attribution set to complete")
response = requests.get(
team_project_url + f"/attributionset/{attribution_set_id}",
headers=headers,
)
if response.json().get("Status") == "complete":
break
print(response.json())
time.sleep(2)
```
### Step 9: Manually Activate the Attribution Set [#step-9-manually-activate-the-attribution-set]
If not activated during creation, send a PATCH request to the `/attributionset/{attribution_set_id}/activate` endpoint to make the new set active.
```python
response = requests.patch(
team_project_url + f"/attributionset/{attribution_set_id}/activate",
headers=headers,
)
```
### Full Example Code [#full-example-code]
```python
import time
import requests
url = "https://app.alviss.io/api/v1/api"
token = ""
team_id = ""
project_id = ""
headers = {"Authorization": "Bearer " + token}
team_project_url = url + f"/projects/{team_id}/{project_id}"
# get active attribution set
response = requests.get(
team_project_url + "/attributionset/active",
headers=headers,
)
attribution_id = 5
attribution_ids = [_attr["IId"] for _attr in response.json()["Attributions"]]
response = requests.post(
team_project_url + "/attributionset_align_dates",
headers=headers,
json={
"attributionjob_ids": [attribution_id, *attribution_ids],
"active": False, # set to True if you want to make this attribution set active
},
)
attribution_set_id = response.json().get("IId")
while True:
print("Waiting for attribution set to complete")
response = requests.get(
team_project_url + f"/attributionset/{attribution_set_id}",
headers=headers,
)
if response.json().get("Status") == "complete":
break
print(response.json())
time.sleep(2)
# manually activate the attribution set
response = requests.patch(
team_project_url + f"/attributionset/{attribution_set_id}/activate",
headers=headers,
)
```
# Filtering and Querying
This tutorial covers the filter query syntax used across all list endpoints in the Alviss AI API. Filters allow you to narrow down results, search by specific criteria, and sort data. We'll cover the syntax, available operators, and provide practical examples.
### Filter Syntax Overview [#filter-syntax-overview]
Filters are passed as JSON strings in the `filters` query parameter. The basic structure is:
```
{"field": [["operator", "value"]]}
```
For multiple conditions on the same field (AND logic):
```
{"field": [["operator1", "value1"], ["operator2", "value2"]]}
```
For multiple filters (OR logic between filters):
```
filters={"field1": [["=", "A"]]}&filters={"field2": [["=", "B"]]}
```
### Available Operators [#available-operators]
| Operator | Description | Example |
| ------------ | ------------------------------------ | ------------------------------------------------------ |
| `=` | Equals | `{"Status": [["=", "COMPLETED"]]}` |
| `!=` | Not equals | `{"Status": [["!=", "FAILED"]]}` |
| `>` | Greater than | `{"CreatedDate": [[">", "2024-01-01"]]}` |
| `>=` | Greater than or equal | `{"IId": [[">=", "100"]]}` |
| `<` | Less than | `{"CreatedDate": [["<", "2024-12-31"]]}` |
| `<=` | Less than or equal | `{"IId": [["<=", "50"]]}` |
| `contains` | String contains (case-sensitive) | `{"Name": [["contains", "Q4"]]}` |
| `startswith` | String starts with | `{"Name": [["startswith", "US_"]]}` |
| `endswith` | String ends with | `{"Name": [["endswith", "_2024"]]}` |
| `ilike` | Case-insensitive like with wildcards | `{"Name": [["ilike", "%marketing%"]]}` |
| `like` | Case-sensitive like with wildcards | `{"Name": [["like", "Model_%"]]}` |
| `in` | Value in list | `{"Country": [["in", "[\"US\", \"UK\", \"DE\"]"]]}` |
| `notin` | Value not in list | `{"Status": [["notin", "[\"FAILED\", \"PENDING\"]"]]}` |
| `is` | Is null/true/false | `{"Note": [["is", "NULL"]]}` |
| `isnot` | Is not null/true/false | `{"Note": [["isnot", "NULL"]]}` |
| `orderby` | Sort results | `{"CreatedDate": [["orderby", "desc"]]}` |
### Nested Field Access [#nested-field-access]
Access fields on related objects using dot notation:
```python
# Filter models by their dataset name
filters = '{"DataSet.Name": [["contains", "Marketing"]]}'
# Filter simulations by the model they use
filters = '{"Model.Name": [["=", "US_Q4_Model"]]}'
# Deep nesting: filter datasets by simulations that used their models
filters = '{"Models.SimulationJobs.Name": [["contains", "Scenario"]]}'
```
### Python Examples [#python-examples]
#### Setup [#setup]
```python
import requests
import json
url = "https://app.alviss.io/api/v1/api"
token = ""
team_id = ""
project_id = ""
headers = {"Authorization": f"Bearer {token}"}
base_url = f"{url}/projects/{team_id}/{project_id}"
```
#### Example 1: Find Completed Models for a Specific Country [#example-1-find-completed-models-for-a-specific-country]
```python
# Find all completed models for the US market
response = requests.get(
f"{base_url}/models",
headers=headers,
params={
"filters": '{"Status": [["=", "COMPLETED"]], "Country": [["=", "US"]]}'
}
)
models = response.json()["items"]
```
#### Example 2: Find Recent Predictions Within a Date Range [#example-2-find-recent-predictions-within-a-date-range]
```python
# Find predictions created in Q4 2024
response = requests.get(
f"{base_url}/predictions",
headers=headers,
params={
"filters": json.dumps({
"Date": [
[">=", "2024-10-01T00:00:00"],
["<=", "2024-12-31T23:59:59"]
]
})
}
)
predictions = response.json()["items"]
```
#### Example 3: Search by Name Pattern [#example-3-search-by-name-pattern]
```python
# Find models whose name contains "Marketing" (case-insensitive)
response = requests.get(
f"{base_url}/models",
headers=headers,
params={
"filters": '{"Name": [["ilike", "%marketing%"]]}'
}
)
```
#### Example 4: Filter by Related Object Properties [#example-4-filter-by-related-object-properties]
```python
# Find simulations that used a specific model
response = requests.get(
f"{base_url}/simulations",
headers=headers,
params={
"filters": '{"Model.IId": [["=", "42"]]}'
}
)
# Find predictions using models trained on a specific dataset
response = requests.get(
f"{base_url}/predictions",
headers=headers,
params={
"filters": '{"Model.DataSet.Name": [["contains", "2024"]]}'
}
)
```
#### Example 5: Using IN Operator for Multiple Values [#example-5-using-in-operator-for-multiple-values]
```python
# Find models for multiple countries
response = requests.get(
f"{base_url}/models",
headers=headers,
params={
"filters": json.dumps({
"Country": [["in", '["US", "UK", "DE", "FR"]']]
})
}
)
```
#### Example 6: Exclude Certain Values [#example-6-exclude-certain-values]
```python
# Find all simulations except failed ones
response = requests.get(
f"{base_url}/simulations",
headers=headers,
params={
"filters": '{"Status": [["notin", "[\\"FAILED\\", \\"PENDING\\"]"]]}'
}
)
```
#### Example 7: Sorting Results [#example-7-sorting-results]
```python
# Get models sorted by creation date (newest first)
response = requests.get(
f"{base_url}/models",
headers=headers,
params={
"filters": '{"CreatedDate": [["orderby", "desc"]]}'
}
)
# Sort by name alphabetically
response = requests.get(
f"{base_url}/models",
headers=headers,
params={
"filters": '{"Name": [["orderby", "asc"]]}'
}
)
```
#### Example 8: Combining Multiple Conditions (AND) [#example-8-combining-multiple-conditions-and]
```python
# Find completed US models created after a specific date
filters = json.dumps({
"Status": [["=", "COMPLETED"]],
"Country": [["=", "US"]],
"CreatedDate": [[">=", "2024-06-01"]]
})
response = requests.get(
f"{base_url}/models",
headers=headers,
params={"filters": filters}
)
```
#### Example 9: OR Logic with Multiple Filter Parameters [#example-9-or-logic-with-multiple-filter-parameters]
```python
# Find models that are either from US OR have "Global" in the name
# Pass multiple filters parameters for OR logic
response = requests.get(
f"{base_url}/models",
headers=headers,
params=[
("filters", '{"Country": [["=", "US"]]}'),
("filters", '{"Name": [["contains", "Global"]]}')
]
)
```
#### Example 10: Check for Null Values [#example-10-check-for-null-values]
```python
# Find models without a note
response = requests.get(
f"{base_url}/models",
headers=headers,
params={
"filters": '{"Note": [["is", "NULL"]]}'
}
)
# Find models that have a note
response = requests.get(
f"{base_url}/models",
headers=headers,
params={
"filters": '{"Note": [["isnot", "NULL"]]}'
}
)
```
### Result Filters for Data Downloads [#result-filters-for-data-downloads]
When downloading data (predictions, simulations, attributions), use `result_filters` to filter the actual data rows:
```python
# Download prediction results for a specific country and variable
response = requests.get(
f"{base_url}/predictions/{prediction_id}/data",
headers=headers,
params={
"result_filters": json.dumps({
"Country": [["=", "US"]],
"Variable": [["contains", "sales"]]
})
}
)
```
### Common Filterable Fields by Endpoint [#common-filterable-fields-by-endpoint]
#### Models (`/models`) [#models-models]
* `IId`, `Name`, `Note`, `Status`, `Country`, `Region`, `Grouping`
* `CreatedDate`, `Selected`, `DataSet.Name`, `DataSet.IId`
#### Predictions (`/predictions`) [#predictions-predictions]
* `IId`, `Name`, `Note`, `Status`, `Date`, `StartDate`, `EndDate`
* `Model.Name`, `Model.IId`, `DataSet.Name`
#### Simulations (`/simulations`) [#simulations-simulations]
* `IId`, `Name`, `Note`, `Status`, `Date`
* `ScenarioStartDate`, `ScenarioEndDate`
* `Model.Name`, `Model.IId`, `DataSet.Name`
#### Optimizations (`/optimizations`) [#optimizations-optimizations]
* `IId`, `Name`, `Note`, `Status`, `Date`
* `Model.Name`, `Model.IId`, `TargetResult`, `Improvement`
#### Attribution Sets (`/attributionset`) [#attribution-sets-attributionset]
* `IId`, `Name`, `Note`, `Status`, `Selected`, `CreatedDate`
* `DataSet.Name`, `Attributions.Name`
### Advanced: Combining Filters with Ordering [#advanced-combining-filters-with-ordering]
You can combine filtering and ordering in a single request. The UI uses this pattern extensively:
```python
# Filter for completed US models AND sort by creation date (newest first)
# Note: ordering is a separate filter object to achieve AND logic
filters_list = [
# First filter: the actual conditions (merged into AND)
json.dumps({
"Status": [["=", "COMPLETED"]],
"Country": [["=", "US"]]
}),
# Second filter: the ordering
json.dumps({
"CreatedDate": [["orderby", "desc"]]
})
]
response = requests.get(
f"{base_url}/models",
headers=headers,
params=[("filters", f) for f in filters_list]
)
```
### Advanced: Filtering by Modelling Combination [#advanced-filtering-by-modelling-combination]
A common pattern is filtering by market segments (Country/Region/Grouping):
```python
# Filter for models in multiple countries
def build_modelling_combination_filter(
countries: list[str] = None,
regions: list[str] = None,
groupings: list[str] = None,
prefix: str = "" # Use "Model." when filtering via related objects
) -> dict:
"""Build a filter dict for modelling combinations."""
filters = {}
if countries:
key = f"{prefix}Country" if prefix else "Country"
filters[key] = [["in", json.dumps(countries)]]
if regions:
key = f"{prefix}Region" if prefix else "Region"
filters[key] = [["in", json.dumps(regions)]]
if groupings:
key = f"{prefix}Grouping" if prefix else "Grouping"
filters[key] = [["in", json.dumps(groupings)]]
return filters
# Example: Find models for US and UK markets
filter_dict = build_modelling_combination_filter(
countries=["US", "UK"],
regions=["all"],
groupings=["retail", "wholesale"]
)
response = requests.get(
f"{base_url}/models",
headers=headers,
params={"filters": json.dumps(filter_dict)}
)
```
### Advanced: Similarity Search for Names [#advanced-similarity-search-for-names]
The API supports fuzzy/similarity search for finding items by name:
```python
# Find models with names similar to "Marketing" (fuzzy search)
response = requests.get(
f"{base_url}/models",
headers=headers,
params={
"filters": '{"Name": [["similarity", "Marketing"]]}'
}
)
```
### Advanced: Dataset-Specific Data Filtering [#advanced-dataset-specific-data-filtering]
When querying data from datasets (Sales, Media, Events, etc.), you can filter by data-specific columns with table prefixes:
```python
# Filter dataset data by product and media attributes
# Note: Use "TableName.Column" format for data-level filtering
filters = json.dumps({
"Sales.Product": [["=", "Health"]],
"Sales.Metric": [["in", '["UnitsSold", "Revenue"]']],
"Country": [["=", "US"]]
})
response = requests.get(
f"{base_url}/datasets/{dataset_id}/data",
headers=headers,
params={"filters": filters}
)
```
### Advanced: Building Complex AND/OR Queries [#advanced-building-complex-andor-queries]
```python
def build_complex_filter(
and_conditions: dict,
or_conditions: list[dict] = None
) -> list[str]:
"""
Build complex filters combining AND and OR logic.
- and_conditions: All conditions that must be true
- or_conditions: List of condition dicts where ANY can be true
Returns list of filter strings to pass as multiple 'filters' params.
"""
filters = []
# AND conditions go in a single filter
if and_conditions:
filters.append(json.dumps(and_conditions))
# OR conditions are separate filters
if or_conditions:
for cond in or_conditions:
filters.append(json.dumps(cond))
return filters
# Example: Find (COMPLETED OR RUNNING) AND (US OR UK) models
# This finds: COMPLETED US, COMPLETED UK, RUNNING US, RUNNING UK
and_conds = {
"Country": [["in", '["US", "UK"]']]
}
or_conds = [
{"Status": [["=", "COMPLETED"]]},
{"Status": [["=", "RUNNING"]]}
]
filter_strings = build_complex_filter(and_conds, or_conds)
response = requests.get(
f"{base_url}/models",
headers=headers,
params=[("filters", f) for f in filter_strings]
)
```
### Tips and Best Practices [#tips-and-best-practices]
1. **URL Encoding**: When using filters in URLs, ensure proper URL encoding of special characters
2. **JSON Escaping**: When nesting JSON (like in the `in` operator), escape inner quotes
3. **Date Format**: Use ISO 8601 format for dates: `2024-01-15T10:30:00`
4. **Performance**: Filter on indexed fields (IId, Status) when possible
5. **Pagination**: Filters work with pagination - use `page` and `size` parameters alongside filters
6. **Combine ordering with filtering**: Use separate filter objects for sorting to ensure proper AND behavior
7. **Use similarity for fuzzy search**: The `similarity` operator is great for user-facing search features
8. **Prefix nested fields**: When filtering through relationships, use dot notation like `Model.DataSet.Name`
### Full Example: Find and Process Matching Models [#full-example-find-and-process-matching-models]
```python
import requests
import json
url = "https://app.alviss.io/api/v1/api"
token = ""
team_id = ""
project_id = ""
headers = {"Authorization": f"Bearer {token}"}
base_url = f"{url}/projects/{team_id}/{project_id}"
# Find all completed US models from Q4 2024
filters = json.dumps({
"Status": [["=", "COMPLETED"]],
"Country": [["=", "US"]],
"CreatedDate": [
[">=", "2024-10-01"],
["<=", "2024-12-31"]
]
})
response = requests.get(
f"{base_url}/models",
headers=headers,
params={
"filters": filters,
"size": 50 # page size
}
)
result = response.json()
models = result["items"]
total = result["total"]
print(f"Found {total} matching models")
for model in models:
print(f" - {model['Name']} (IId: {model['IId']}, Created: {model['CreatedDate']})")
# If there are more pages, iterate
page = 2
while len(models) < total:
response = requests.get(
f"{base_url}/models",
headers=headers,
params={
"filters": filters,
"size": 50,
"page": page
}
)
models.extend(response.json()["items"])
page += 1
```
# Set Variable Dimensions On Attribution
This tutorial covers downloading attribution data, fetching the associated variable metadata, and merging them together so that dimension attributes (such as product category, channel, or any custom dimensions) are available as columns on each attribution row. This is useful for filtering, grouping, and analysing attribution results by the dimensions defined on your variables and response curves. We'll walk through the process step by step using Python with the `requests` and `pandas` libraries to interact with the Alviss AI API. For each step, the relevant valid Python code snippet is provided.
### Prerequisites [#prerequisites]
* You need a valid access token from the Alviss AI platform (see the Authentication section in the main API docs).
* Know your team ID, project ID, and the attribution ID you want to enrich.
* Install the required Python libraries if not already present: `pip install requests pandas`.
### Step 1: Import Necessary Libraries [#step-1-import-necessary-libraries]
Import `requests` for making HTTP API calls, `io` for handling byte streams, and `pandas` for data manipulation.
```python
import requests
import io
import pandas as pd
```
### Step 2: Set Up Variables [#step-2-set-up-variables]
Define the base API URL, your access token, team ID, project ID, and the attribution ID. Replace placeholders like `` with actual values.
```python
url = "https://app.alviss.io/api/v1/api"
team_id = ""
project_id = ""
token = ""
attribution_id = 12
```
### Step 3: Prepare Authentication Headers [#step-3-prepare-authentication-headers]
Create a headers dictionary with the Authorization Bearer token to authenticate all API requests.
```python
headers = {"Authorization": "Bearer " + token}
```
### Step 4: Construct the Project URL [#step-4-construct-the-project-url]
Build the base URL for the team and project-specific endpoints by formatting the team ID and project ID into the URL string.
```python
team_project_url = url + f"/projects/{team_id}/{project_id}"
```
### Step 5: Download Attribution Data [#step-5-download-attribution-data]
Send a GET request to the `/attributions/{attribution_id}/data` endpoint. The response contains CSV-formatted attribution results which we parse into a DataFrame using `pandas`.
```python
resp = requests.get(
team_project_url + f"/attributions/{attribution_id}/data",
headers=headers,
)
df = pd.read_csv(io.BytesIO(resp.content))
```
### Step 6: Fetch Variable Metadata [#step-6-fetch-variable-metadata]
Send a GET request to the `/attributions/{attribution_id}/variables` endpoint. The response is a JSON array of variable definitions including their dimension attributes (`util_attr`) and linked response curve information (`attribution_response`).
```python
resp = requests.get(
team_project_url + f"/attributions/{attribution_id}/variables",
headers=headers,
)
df_vars = pd.DataFrame(resp.json())
```
### Step 7: Reshape Variable Metadata [#step-7-reshape-variable-metadata]
Select and rename the columns we need for the merge: the variable slug, its dimension attributes, the linked response curve slug, and the response curve dimension attributes.
```python
df_vars = pd.DataFrame(
{
"Variable": df_vars["Slug"],
"util_attr": df_vars["util_attr"],
"Response": df_vars["attribution_response"].str["Slug"],
"response_util_attr": df_vars["attribution_response"].str["util_attr"],
}
)
```
### Step 8: Merge Attribution Data with Variable Metadata [#step-8-merge-attribution-data-with-variable-metadata]
Join the attribution data with the variable metadata on the `Variable` and `Response` columns. This adds the dimension attribute dictionaries to each attribution row.
```python
merge_df = pd.merge(df, df_vars, on=["Variable", "Response"])
```
### Step 9: Expand Dimension Attributes into Columns [#step-9-expand-dimension-attributes-into-columns]
Use `pd.json_normalize` to flatten the dimension attribute dictionaries into individual columns. Variable dimensions are prefixed with `Var_` and response curve dimensions with `Resp_` to avoid name collisions. The original dictionary columns are dropped and replaced by the expanded ones.
```python
var_attrs = pd.json_normalize(
merge_df["util_attr"].apply(lambda x: x or {})
).add_prefix("Var_")
resp_attrs = pd.json_normalize(
merge_df["response_util_attr"].apply(lambda x: x or {})
).add_prefix("Resp_")
merge_df = pd.concat(
[merge_df.drop(columns=["util_attr", "response_util_attr"]), var_attrs, resp_attrs],
axis=1,
)
```
The resulting `merge_df` DataFrame now contains all original attribution columns plus one column per dimension attribute, ready for downstream analysis.
### Full Example Code [#full-example-code]
```python
import requests
import io
import pandas as pd
url = "https://app.alviss.io/api/v1/api"
team_id = ""
project_id = ""
token = ""
attribution_id = 12
headers = {"Authorization": "Bearer " + token}
team_project_url = url + f"/projects/{team_id}/{project_id}"
resp = requests.get(
team_project_url + f"/attributions/{attribution_id}/data",
headers=headers,
)
df = pd.read_csv(io.BytesIO(resp.content))
resp = requests.get(
team_project_url + f"/attributions/{attribution_id}/variables",
headers=headers,
)
df_vars = pd.DataFrame(resp.json())
df_vars = pd.DataFrame(
{
"Variable": df_vars["Slug"],
"util_attr": df_vars["util_attr"],
"Response": df_vars["attribution_response"].str["Slug"],
"response_util_attr": df_vars["attribution_response"].str["util_attr"],
}
)
merge_df = pd.merge(df, df_vars, on=["Variable", "Response"])
var_attrs = pd.json_normalize(
merge_df["util_attr"].apply(lambda x: x or {})
).add_prefix("Var_")
resp_attrs = pd.json_normalize(
merge_df["response_util_attr"].apply(lambda x: x or {})
).add_prefix("Resp_")
merge_df = pd.concat(
[merge_df.drop(columns=["util_attr", "response_util_attr"]), var_attrs, resp_attrs],
axis=1,
)
```
# Upload Data
This tutorial covers uploading a file, creating a dataset from it, and activating the dataset. This is useful for initializing data in Alviss AI projects. We'll walk through the process step by step using Python with the `requests` library to interact with the Alviss AI API. For each step, the relevant valid Python code snippet is provided.
### Prerequisites [#prerequisites]
* You need a valid access token from the Alviss AI platform (see the Authentication section in the main API docs).
* Know your team ID and project ID.
* Have the file you want to upload ready (e.g., a CSV or other supported format for datasets like "Sales").
* Install the required Python libraries if not already present: `pip install requests` (though it's standard).
### Step 1: Import Necessary Libraries [#step-1-import-necessary-libraries]
Import `time` for handling delays in polling and `requests` for making HTTP API calls.
```python
import time
import requests
```
### Step 2: Set Up Variables [#step-2-set-up-variables]
Define the base API URL, your access token, team ID, project ID, and the local path to the file you want to upload. Replace placeholders like `` with actual values.
```python
url = "https://app.alviss.io/api/v1/api"
token = "" # access token created in https://app.alviss.io/-/user
team_id = ""
project_id = ""
file_path = "" # the file we want to upload
```
### Step 3: Prepare Authentication Headers [#step-3-prepare-authentication-headers]
Create a headers dictionary with the Authorization Bearer token to authenticate all API requests.
```python
headers = {"Authorization": "Bearer " + token}
```
### Step 4: Construct the Project URL [#step-4-construct-the-project-url]
Build the base URL for the team and project-specific endpoints by formatting the team ID and project ID into the URL string.
```python
team_project_url = url + f"/projects/{team_id}/{project_id}"
```
### Step 5: Upload the File [#step-5-upload-the-file]
Send a POST request to the `/datauploads` endpoint. Include the dataset name (e.g., "Sales") as a query parameter and attach the file using the `files` parameter. This initiates the upload and returns an `upload_id` in the response.
```python
response = requests.post(
team_project_url + "/datauploads",
headers=headers,
params={"dataset_name": "Sales"}, # the file type: [Sales,Events, Media, Extra, .....]
files={"file": open(file_path, "rb")},
)
upload_id = response.json().get("upload_id")
```
### Step 6: Poll for Upload Completion [#step-6-poll-for-upload-completion]
Use a while loop to repeatedly send GET requests to check the status of the upload using the `upload_id`. Print the response for debugging and sleep for 1 second between checks. Break when the status is "complete".
```python
while True:
response = requests.get(
team_project_url + f"/datauploads/{upload_id}",
headers=headers,
)
if response.json().get("Status") == "complete":
break
print(response.json())
time.sleep(1)
```
### Step 7: Create the Dataset [#step-7-create-the-dataset]
Send a POST request to the `/datasets` endpoint with the `upload_id` in the JSON payload. Optionally, you can activate it immediately or extend an existing dataset by uncommenting the relevant lines. This returns a `dataset_id`.
```python
response = requests.post(
team_project_url + "/datasets",
headers=headers,
json={
"upload_ids": [upload_id],
# "activate": True, # if one want to activate the dataset right away
# "dataset_ids": [8], # used to extend a dataset
},
)
dataset_id = response.json().get("IId")
```
### Step 8: Poll for Dataset Completion [#step-8-poll-for-dataset-completion]
Similar to Step 6, poll the dataset's status using GET requests until it's "complete".
```python
while True:
response = requests.get(
team_project_url + f"/datasets/{dataset_id}",
headers=headers,
)
if response.json().get("Status") == "complete":
break
print(response.json())
time.sleep(1)
```
### Step 9: Activate the Dataset [#step-9-activate-the-dataset]
If not activated during creation, send a POST request to the `/datasets/{dataset_id}/activate` endpoint to make the dataset active for use.
```python
response = requests.post(
team_project_url + f"/datasets/{dataset_id}/activate",
headers=headers,
)
```
### Full Example Code [#full-example-code]
```python
"""
Script to upload files and create a dataset in Alviss AI.
See https://api.alviss.io/v1/api/docs#/ for the API documentation.
"""
import time
import requests
url = "https://app.alviss.io/api/v1/api"
token = "" # access token created in https://app.alviss.io/-/user
team_id = ""
project_id = ""
file_path = "" # the file we want to upload
headers = {"Authorization": "Bearer " + token}
team_project_url = url + f"/projects/{team_id}/{project_id}"
# Create a data upload
response = requests.post(
team_project_url + "/datauploads",
headers=headers,
params={"dataset_name": "Sales"}, # the file type: [Sales,Events, Media, Extra, .....]
files={"file": open(file_path, "rb")},
)
# wait for the dataupload to be completed
upload_id = response.json().get("upload_id")
while True:
response = requests.get(
team_project_url + f"/datauploads/{upload_id}",
headers=headers,
)
if response.json().get("Status") == "complete":
break
print(response.json())
time.sleep(1)
# create the dataset
response = requests.post(
team_project_url + "/datasets",
headers=headers,
json={
"upload_ids": [upload_id],
# "activate": True, # if one want to activate the dataset right away
# "dataset_ids": [8], # used to extend a dataset
},
)
dataset_id = response.json().get("IId")
# wait for the dataupload to complete
while True:
response = requests.get(
team_project_url + f"/datasets/{dataset_id}",
headers=headers,
)
if response.json().get("Status") == "complete":
break
print(response.json())
time.sleep(1)
# activate the dataset
response = requests.post(
team_project_url + f"/datasets/{dataset_id}/activate",
headers=headers,
)
```
# Upload, Refit And Attribute
## Upload, Refit, and Attribute Tutorial [#upload-refit-and-attribute-tutorial]
This tutorial covers a basic scenario for continuous updates in Alviss AI: uploading new data, creating a new dataset by extending the active one, refitting an existing model with the updated dataset, and creating an attribution. This is useful for maintaining and updating models with fresh data in ongoing projects. We'll walk through the process step by step using Python with the `requests` library to interact with the Alviss AI API. For each step, the relevant valid Python code snippet is provided.
### Prerequisites [#prerequisites]
* You need a valid access token from the Alviss AI platform (see the Authentication section in the main API docs).
* Know your team ID, project ID, and an existing model ID to refit.
* Have the file with new data ready (e.g., a CSV or other supported format for datasets like "Sales").
* Define model-specific details like country, region, and grouping based on your project.
* Install the required Python libraries if not already present: `pip install requests` (though it's standard).
### Step 1: Import Necessary Libraries [#step-1-import-necessary-libraries]
Import `time` for handling delays in polling and `requests` for making HTTP API calls.
```python
import time
import requests
```
### Step 2: Set Up Variables [#step-2-set-up-variables]
Define the base API URL, your access token, team ID, project ID, and the local path to the file with new data. Also, specify the existing model ID and model details like country, region, and grouping. Replace placeholders like `` with actual values.
```python
url = "https://app.alviss.io/api/v1/api"
token = ""
team_id = ""
project_id = ""
file_path = ""
# Model refit specifics
existing_model_id = 3
model_country = "SWE"
model_region = "all"
model_grouping = "all"
```
### Step 3: Prepare Authentication Headers [#step-3-prepare-authentication-headers]
Create a headers dictionary with the Authorization Bearer token to authenticate all API requests.
```python
headers = {"Authorization": "Bearer " + token}
```
### Step 4: Construct the Project URL [#step-4-construct-the-project-url]
Build the base URL for the team and project-specific endpoints by formatting the team ID and project ID into the URL string.
```python
team_project_url = url + f"/projects/{team_id}/{project_id}"
```
### Step 5: Upload the New Data File [#step-5-upload-the-new-data-file]
Send a POST request to the `/datauploads` endpoint. Include the dataset name (e.g., "Sales") as a query parameter and attach the file using the `files` parameter. This initiates the upload and returns an `upload_id` in the response.
```python
response = requests.post(
team_project_url + "/datauploads",
headers=headers,
params={"dataset_name": "Sales"},
files={"file": open(file_path, "rb")},
)
upload_id = response.json().get("upload_id")
```
### Step 6: Poll for Upload Completion [#step-6-poll-for-upload-completion]
Use a while loop to repeatedly send GET requests to check the status of the upload using the `upload_id`. Print progress messages and the response for debugging, and sleep for 2 seconds between checks. Break when the status is "complete".
```python
while True:
print("Waiting for upload to complete")
response = requests.get(
team_project_url + f"/datauploads/{upload_id}",
headers=headers,
)
if response.json().get("Status") == "complete":
break
print(response.json())
time.sleep(2)
```
### Step 7: Get the Active Dataset ID [#step-7-get-the-active-dataset-id]
Send a GET request to the `/datasets/active` endpoint to retrieve the ID of the currently active dataset, which will be extended with the new upload.
```python
response = requests.get(
team_project_url + "/datasets/active",
headers=headers,
)
active_dataset_id = response.json()["IId"]
```
### Step 8: Create a New Dataset [#step-8-create-a-new-dataset]
Send a POST request to the `/datasets` endpoint to create a new dataset by combining the new upload ID with the active dataset ID. This extends the existing data. The response returns a new `dataset_id`.
```python
response = requests.post(
team_project_url + "/datasets",
headers=headers,
json={"upload_ids": [upload_id], "dataset_ids": [active_dataset_id]},
)
dataset_id = response.json().get("IId")
```
### Step 9: Poll for Dataset Completion [#step-9-poll-for-dataset-completion]
Use a while loop to repeatedly send GET requests to check the status of the new dataset. Print progress messages and the response for debugging, and sleep for 2 seconds between checks. Break when the status is "complete".
```python
while True:
print("Waiting for dataset to complete")
response = requests.get(
team_project_url + f"/datasets/{dataset_id}",
headers=headers,
)
if response.json().get("Status") == "complete":
break
print(response.json())
time.sleep(2)
```
### Step 10: Retrieve Dataset Dates [#step-10-retrieve-dataset-dates]
Send a POST request to the `/datasets/{dataset_id}/dates` endpoint with the dataset name as a parameter and model-specific filters in the JSON payload. This returns a list of `data_dates` for training and evaluation splitting.
```python
response = requests.post(
team_project_url + f"/datasets/{dataset_id}/dates",
headers=headers,
params={"dataset_name": "Sales"},
json=[
{
"country_code": model_country,
"region_code": model_region,
"grouping": model_grouping,
}
],
)
data_dates = response.json()
```
### Step 11: Split Dates for Training and Evaluation [#step-11-split-dates-for-training-and-evaluation]
Calculate a separator index at 75% of the data dates length, then slice the list to create `train_dates` and `eval_dates` for model refitting.
```python
separator_date = int(len(data_dates) * 0.75)
train_dates = data_dates[:separator_date]
eval_dates = data_dates[separator_date:]
```
### Step 12: Refit the Model [#step-12-refit-the-model]
Send a POST request to the `/models/{existing_model_id}/refit` endpoint with details about the new dataset, dates, and model parameters in the JSON payload. This starts the refit process and returns a new `model_id`.
```python
response = requests.post(
team_project_url + f"/models/{existing_model_id}/refit",
headers=headers,
json={
"model_detail": {
"dataset_id": dataset_id,
"train_dates": train_dates,
"eval_dates": eval_dates,
},
"model_param": {"epochs": 500, "learning_rate": 0.001, "samples": 3},
},
)
model_id = response.json()["IId"]
```
### Step 13: Poll for Model Refit Completion [#step-13-poll-for-model-refit-completion]
Use a while loop to repeatedly send GET requests to check the status of the refitted model. Print progress messages and the response for debugging, and sleep for 2 seconds between checks. Break when the status is "completed".
```python
while True:
print("Waiting for model to complete")
response = requests.get(
team_project_url + f"/models/{model_id}",
headers=headers,
)
if response.json().get("Status") == "completed":
break
print(response.json())
time.sleep(2)
```
### Step 14: Create an Attribution [#step-14-create-an-attribution]
Send a POST request to the `/attributions` endpoint with the new model ID, dataset ID, date range, and samples in the JSON payload. This creates an attribution and returns an `attribution_id`.
```python
response = requests.post(
team_project_url + "/attributions",
headers=headers,
json={
"model_id": model_id,
"dataset_id": dataset_id,
"start_date": data_dates[0],
"end_date": data_dates[-1],
"samples": 20,
},
)
attribution_id = response.json()["IId"]
```
### Step 15: Poll for Attribution Completion [#step-15-poll-for-attribution-completion]
Use a while loop to repeatedly send GET requests to check the status of the attribution. Print progress messages and the response for debugging, and sleep for 2 seconds between checks. Break when the status is "completed".
```python
while True:
print("Waiting for attribution to complete")
response = requests.get(
team_project_url + f"/attributions/{attribution_id}",
headers=headers,
)
if response.json().get("Status") == "completed":
break
print(response.json())
time.sleep(2)
```
### Full Example Code [#full-example-code]
```python
import time
import requests
url = "https://app.alviss.io/api/v1/api"
token = ""
team_id = ""
project_id = ""
file_path = ""
headers = {"Authorization": "Bearer " + token}
team_project_url = url + f"/projects/{team_id}/{project_id}"
# Model refit with new dataset
existing_model_id = 3
model_country = "SWE"
model_region = "all"
model_grouping = "all"
response = requests.post(
team_project_url + "/datauploads",
headers=headers,
params={"dataset_name": "Sales"},
files={"file": open(file_path, "rb")},
)
upload_id = response.json().get("upload_id")
while True:
print("Waiting for upload to complete")
response = requests.get(
team_project_url + f"/datauploads/{upload_id}",
headers=headers,
)
if response.json().get("Status") == "complete":
break
print(response.json())
time.sleep(2)
# get active dataset
response = requests.get(
team_project_url + "/datasets/active",
headers=headers,
)
active_dataset_id = response.json()["IId"]
response = requests.post(
team_project_url + "/datasets",
headers=headers,
json={"upload_ids": [upload_id], "dataset_ids": [active_dataset_id]},
)
dataset_id = response.json().get("IId")
while True:
print("Waiting for dataset to complete")
response = requests.get(
team_project_url + f"/datasets/{dataset_id}",
headers=headers,
)
if response.json().get("Status") == "complete":
break
print(response.json())
time.sleep(2)
response = requests.post(
team_project_url + f"/datasets/{dataset_id}/dates",
headers=headers,
params={"dataset_name": "Sales"},
json=[
{
"country_code": model_country,
"region_code": model_region,
"grouping": model_grouping,
}
],
)
data_dates = response.json()
separator_date = int(len(data_dates) * 0.75)
train_dates = data_dates[:separator_date]
eval_dates = data_dates[separator_date:]
response = requests.post(
team_project_url + f"/models/{existing_model_id}/refit",
headers=headers,
json={
"model_detail": {
"dataset_id": dataset_id,
"train_dates": train_dates,
"eval_dates": eval_dates,
},
"model_param": {"epochs": 500, "learning_rate": 0.001, "samples": 3},
},
)
model_id = response.json()["IId"]
while True:
print("Waiting for model to complete")
response = requests.get(
team_project_url + f"/models/{model_id}",
headers=headers,
)
if response.json().get("Status") == "completed":
break
print(response.json())
time.sleep(2)
# run attribution
response = requests.post(
team_project_url + "/attributions",
headers=headers,
json={
"model_id": model_id,
"dataset_id": dataset_id,
"start_date": data_dates[0],
"end_date": data_dates[-1],
"samples": 20,
},
)
attribution_id = response.json()["IId"]
while True:
print("Waiting for attribution to complete")
response = requests.get(
team_project_url + f"/attributions/{attribution_id}",
headers=headers,
)
if response.json().get("Status") == "completed":
break
print(response.json())
time.sleep(2)
```
# Building Your First Model
Welcome back to the Alviss AI Getting Started series! Now that you've created your first [Dataset](Create%20Dataset), the next step is to build a model. We'll use the [Basic Model Builder](../../docs/Models/Basic%20Model%20Builder) for this, as it's a quick and efficient way to get started. It automates much of the process with sensible defaults, letting you focus on key decisions while the platform handles the details.
This tutorial will guide you through creating a basic model, from selection to training. Once complete, your model will be ready for insights like [Attributions](../../docs/Attributions), [Simulations](../../docs/Simulations), [Predictions](../../docs/Predictions), and [Optimizations](../../docs/Optimizations).
## Step 1: Navigating to Model Creation [#step-1-navigating-to-model-creation]
1. Log in to Alviss AI and open the project where you created your Dataset.
2. In the side menu, navigate to **Models**.
3. Click **New Model** to begin.
## Step 2: Setting Model Name and Notes [#step-2-setting-model-name-and-notes]
Optionally, provide a **Name** for your model (e.g., "Initial Sales Model") and add **Notes** for bookkeeping. If no name is set, the platform assigns a random one (displayed in gray).
This helps track models as your project grows.
## Step 3: Selecting the Dataset [#step-3-selecting-the-dataset]
Choose the [Dataset](../../docs/Data/Datasets) to use as the model's foundation. This provides the raw data, such as sales figures, marketing spend, or external factors. Ensure it matches your project's [periodicity](../../docs/Data/Format/Periodicity) and has been quality-checked (e.g., via the [Activities](../../docs/Activities) dashboard).
If your Dataset isn't listed, double-check it's [activated](../../docs/Data/Datasets#active-dataset) or create a new one following the previous tutorial.
## Step 4: Defining Modeling Combinations [#step-4-defining-modeling-combinations]
Specify the \[modeling combinations]\(../../docs/Models/Modeling Combination) based on dimensions like country, region, or grouping. For each unique combination (e.g., "SWE - all - all"), Alviss AI builds a dedicated model. This enables granular insights while scaling across your data.
Combinations allow tailored modeling—e.g., separate models for different regions if their data behaves independently.
## Step 5: Selecting Target Variables [#step-5-selecting-target-variables]
If your Dataset includes multiple sales variables, choose which ones to model as targets (e.g., revenue or units sold). By default, all available sales variables are included.
This defines the KPIs your model will predict or analyze.
## Step 6: Configuring Input Variable Groups [#step-6-configuring-input-variable-groups]
Define groups of input variables from your Dataset to include in the model. Examples include Media (ad spend), Season (holiday effects), Trend (market shifts), Pricing, and more.
### Sub-Configurations for Variable Groups [#sub-configurations-for-variable-groups]
* **Variables:** Select specific variables within the group to use. If not specified, all are included.
* **Influence:** Set how the group impacts the KPI:
* **Positive:** Increases lead to higher sales (e.g., media investments).
* **Negative:** Increases lead to lower sales (e.g., competitor distribution).
* **Neutral:** Could go either way (e.g., weather).
This enforces behavior in the model—e.g., positive influences won't produce negative effects.
* **Effect:** Toggle on to estimate how much of the sales variance is explained by this group.
Enabling "Effect" for more groups increases training time but doesn't affect runtime for [Simulations](../../docs/Simulations) or [Predictions](../../docs/Predictions).
* **Other Configs:** Group-specific options may appear, such as:
* **Effect In Days:** For media, specify how many days into the future an investment impacts sales.
* **Match Product:** Align variables to specific products in the KPI; unmatched ones are excluded.
* **Net Profit:** Create a "NetProfit" node (Profit - Investments) for display in dashboards as a response metric.
Customize these to fit your data's nuances.
## Step 7: Setting the Date Range [#step-7-setting-the-date-range]
Define the data periods for training and holdout (validation). You can select multiple periods, even with gaps.
Holdout data helps evaluate model performance on unseen data. Gaps are fine if your data has natural breaks (e.g., seasonal pauses).
## Step 8: Creating and Monitoring the Model [#step-8-creating-and-monitoring-the-model]
1. Review your selections.
2. Click **Create** to submit the model for training.
The model will progress through states:
* **Submitted:** Queued for training.
* **Running:** Actively training.
* **Completed:** Ready to use.
* **Failed:** An error occurred—check the model details page for messages.
Once **Completed**, navigate to the model's details to view results such as
* Performance metrics
* Fit Prediction
* Attribution of model
Training time varies based on Dataset size and configurations (e.g., more "Effect" groups). Monitor progress in the Models list.
This completes the model-building tutorial. If you want to better understand how to inspect the model have a look at the following tutorials.
* [Evaluating Model Fit](../Inspect%20Model/Evaluating%20Model%20Fit)
* [Business Sanity](../Inspect%20Model/Business%20Sanity)
# Create Dataset
Welcome to the Alviss AI Getting Started series! This tutorial focuses on the essential first step: creating a Dataset. Datasets are the foundation for building models, running simulations, predictions, optimizations, and more. Before diving into advanced features, you'll need to upload and organize your data correctly.
We'll walk through transforming your raw data into the supported format, uploading it to the platform, and finally creating a Dataset. By the end, you'll have a ready-to-use Dataset for your projects.
## Step 1: Transforming Your Data [#step-1-transforming-your-data]
Alviss AI requires data to be structured in a specific way for accurate modeling. You can upload data in either **wide format** (where each column represents a variable) or **long format** (where each row corresponds to a single data entry). The choice doesn't affect platform behavior post-upload, so pick whichever is easiest to transform from your current data sources.
You can mix wide and long formats across different files without issues.
Let's use sales data as an example to illustrate.
### Long Format Example (Sales Data) [#long-format-example-sales-data]
In long format, each row is a unique observation:
| Country | Region | Grouping | Date | Product | UnitsSold | PricePerUnit | ProfitPerUnit |
| ------- | ------ | -------- | ---------- | ------- | --------- | ------------ | ------------- |
| SWE | all | all | 2018-01-07 | Health | 292.00 | 362.9658 | 120.0 |
| SWE | all | all | 2018-01-07 | Life | 1489.00 | 1990.8113 | 550.0 |
| SWE | all | all | 2018-01-07 | Pc | 30212.33 | 546.3061 | 220.0 |
| SWE | all | all | 2018-01-14 | Health | 275.00 | 391.5818 | 120.0 |
| SWE | all | all | 2018-01-14 | Life | 1359.00 | 5241.0199 | 550.0 |
| SWE | all | all | 2018-01-14 | Pc | 27306.00 | 478.0982 | 220.0 |
### Wide Format Example (Sales Data) [#wide-format-example-sales-data]
In wide format, variables are spread across columns:
| Country | SWE | SWE | SWE | SWE | SWE | SWE |
| ---------- | --------- | --------- | ----------- | ------------ | ------------ | ------------ |
| Region | all | all | all | all | all | all |
| Product | Health | Life | Pc | Health | Life | Pc |
| Grouping | all | all | all | all | all | all |
| Metric | UnitsSold | UnitsSold | UnitsSold | PricePerUnit | PricePerUnit | PricePerUnit |
| 2018-01-08 | 292 | 1489 | 30212.33333 | 362.9657534 | 1990.811283 | 546.3061282 |
| 2018-01-15 | 275 | 1359 | 27306 | 391.5818182 | 5241.0199 | 478.0982202 |
| 2018-01-22 | 359 | 1431 | 25467 | 285.7465181 | 2303.684836 | 417.5839321 |
| 2018-01-29 | 411 | 1481 | 22027 | 306.7177616 | 4008.871708 | 345.5292141 |
| 2018-02-05 | 533 | 2382 | 50881 | 361.6679174 | 2419.802687 | 348.0693776 |
### Key Fields Common to All Files [#key-fields-common-to-all-files]
These fields are required in every data file and define the structure of your data:
* **[Country](../../docs/Data/Format/Country)** (string, required): Use a three-letter ISO 3166 code (e.g., "SWE" for Sweden) to indicate where the data originates.
* **[Region](../../docs/Data/Format/Region)** (string, required): Specify a region within the country (e.g., "all" for nationwide or an ISO 3166-2 code like "SE-AB" for Stockholm County).
* **[Grouping](../../docs/Data/Format/Grouping)** (string, optional): For extra segmentation, such as sales channels or customer types (e.g., "all" if not needed).
How you segment data into country, region, and grouping affects modeling: each unique combination gets its own model. Simulations, predictions, and optimizations operate at this level. Aim for independence—e.g., if marketing in Norway doesn't affect Germany, structure by country. If no further split is needed, use "all" for region and grouping.
* **[Date](../../docs/Data/Format/Date)** (required): Must follow ISO 8601 format for consistency:
* Basic: `YYYY-MM-DD` (e.g., 2018-01-07).
* With time: `YYYY-MM-DDTHH:MM:SS` (e.g., 2018-01-07T14:30:00).
* With timezone: Append `±HH:MM` (e.g., 2018-01-07T14:30:00+01:00).
Using ISO 8601 avoids errors in temporal alignment.
### File-Specific Information [#file-specific-information]
Beyond the common fields, each file type has unique requirements. For sales data (as in our example):
* **UnitsSold** (integer or float, required): Number of units sold (e.g., 292). Fractions are okay for averages.
* **PricePerUnit** (float, required): Average price per unit in local currency (e.g., 362.97). Use period (.) as decimal separator.
* **ProfitPerUnit** (float, optional): Average profit per unit (e.g., 120.0). Include for margin analysis.
* **Product** (string, required): Product identifier (e.g., "Health", "Life", "Pc").
Text fields (e.g., Product) only allow: `0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZåäöüøæÆÄÅÖÜßØ()_+-`. Avoid special characters to prevent upload errors.
Alviss AI supports various file types for different data aspects. Here's a quick overview (see linked docs for details):
* [Sales](../../docs/Data/Files/Sales): Tracks units, prices, and profits for revenue modeling.
* [Brand](../../docs/Data/Files/Brand): Brand perception metrics like awareness and liking.
* [Competitor Brand](../../docs/Data/Files/Competitor%20Brand): Competitors' perception metrics.
* [Distribution](../../docs/Data/Files/Distribution): Network metrics like store counts.
* [Competitor Distribution](../../docs/Data/Files/Competitor%20Distribution): Competitors' distribution data.
* [Media](../../docs/Data/Files/Media): Advertising investments and metrics (e.g., impressions).
* [Competitor Media](../../docs/Data/Files/Competitor%20Media): Competitors' media data.
* [Competitor Price](../../docs/Data/Files/Competitor%20Price): Competitors' pricing for elasticity analysis.
* [Customer Experience](../../docs/Data/Files/Customer%20Experience): CX investments for ROI estimation.
* [Events](../../docs/Data/Files/Events): Disruptions like outages.
* [Extra](../../docs/Data/Files/Extra): Custom variables.
* [Macro](../../docs/Data/Files/Macro): Economic indicators like unemployment.
* [Visits](../../docs/Data/Files/Visits): Traffic metrics to sites or stores.
* [Weather](../../docs/Data/Files/Weather): Environmental data like precipitation.
Ensure your data matches the project's granularity (set during project creation—e.g., daily, weekly).
## Step 2: Saving in the Right File Format [#step-2-saving-in-the-right-file-format]
Once structured, save your files in a supported format:
* **CSV (Comma-Separated Values):** Simple text files. Use commas as separators.
In Excel, some regions default to semicolons (;). Explicitly choose commas when saving as CSV.
* **Excel (.xlsx):** Standard spreadsheet format.
Excel may change dates based on your locale (e.g., MM/DD/YYYY). Export dates as text or force ISO 8601 to avoid issues.
For full details, see [File Format](../../docs/Data/Format/File%20Format).
## Step 3: Uploading the Files [#step-3-uploading-the-files]
With files ready:
1. Log in to Alviss AI and open your desired project.
2. Navigate to **Data > Uploads**.
3. Click **Upload New Data**.
4. On the upload page:
* Optionally set a custom **Name** for the batch (e.g., "Q3\_2025\_Sales\_Data\_").
* Drag and drop or click to select files for each file type (e.g., Sales, Media).
5\. The platform checks for inconsistencies during upload and notifies you of issues.
## Step 4: Creating the Dataset [#step-4-creating-the-dataset]
After uploading, create a Dataset to bundle files for use in modeling:
1. From the uploads page, click **Create a New Dataset** using your uploaded files.
2. Set a **Name** for the Dataset and add optional notes.
3. Optionally **extend an existing Dataset** with these new files.
4. Include **previous uploads** if needed.
5. Add **external variables** (e.g., custom metrics).
6. Click **Create Dataset**. You'll be redirected to the Dataset's details page.
Your Dataset is now active and ready! Activate it as the [Active Dataset](../../docs/Data/Datasets#active-dataset) to use it in dashboards like [Activities](../../docs/Activities) or proceed to model building.
Inspect your data in the [Activities](../../docs/Activities) dashboard for outliers or issues before modeling. Use [Filtering](../../docs/Filtering) for precise anal
ysis.
This completes the Dataset creation tutorial. Next in the series: Building Your First Model. If you encounter issues, refer to the full [Data Specification](../../docs/Data/Files). Happy analyzing!
# Run A Prediction
With a [Dataset](Create%20Dataset) created and your first [Model](Building%20Your%20First%20Model) built, you're ready to run a Prediction. This tutorial guides you through forecasting sales based on modified media variables. Predictions emphasize absolute forecasts for planning (e.g., total sales projections), differing from [Simulations](Run%20a%20Simulation), which focus on comparative differences for "what-if" analysis. If differentials suit your needs better, explore the Simulations tutorial instead.
### Prerequisites [#prerequisites]
* An active project with a Dataset and trained Model.
* Access to the Predictions section (team role-dependent; see [Permissions and Roles](../../docs/users/Permissions%20and%20Roles)).
### Step 1: Start a New Prediction [#step-1-start-a-new-prediction]
Navigate to Predictions in the side menu and click "New Prediction."
### Step 2: Configure Basic Settings [#step-2-configure-basic-settings]
1. **Name (Optional):** Enter a descriptive name, or let Alviss AI generate one.
2. **Modeling Combination:** Select from available options.
3. **Advanced Options (If Available):** Choose a specific model and dataset.
4. **Date Range:** Set the prediction period.
### Step 3: Select Variables [#step-3-select-variables]
Choose variables to modify (e.g., media channels). Unselected ones use dataset defaults.
For this example, select all media-related variables.
### Step 4: Modify the Scenario [#step-4-modify-the-scenario]
Use bulk actions for quick setup, then fine-tune as needed.
For a full guide on using the interface—including aggregation modes, patterns (Historical, Constant, Custom), scaling (Additive, Multiplicative), bounds controls, and per-time-point edits—see [Modifying Scenario and Baseline](../../docs/Simulations#modifying-scenario-and-baseline).
### Step 5 (Optional): Additional Scenarios [#step-5-optional-additional-scenarios]
To compare multiple forecasts, copy the current scenario or add a new one and configure from scratch.
### Step 6: Run and Review [#step-6-run-and-review]
Click "Create Prediction." It processes in the background.
Once ready, explore results with a tab per scenario:
For each:
* **Summary Numbers:** Key aggregates like total projected sales.
* **Visuals:** Total Effect, Product Over Time, Cumulative Product.
* **Tools:** Switch to tables, toggle uncertainty, apply filters.
In this media example, adjust spends to forecast sales under different investment levels. Experiment to uncover insights!
For conceptual details, refer to [Predictions](../../docs/Predictions). Next, try [Optimizations](Run%20an%20Optimization).
# Run A Simulation
With a [Dataset](Create%20Dataset) created and your first [Model](Building%20Your%20First%20Model) built, you're ready to run a Simulation. This tutorial walks through creating one to measure media impact—comparing a "high-spend" scenario against a "no-spend" baseline. Simulations excel at differential analysis (e.g., "How much more sales does Plan A yield vs. Plan B?"), differing from [Predictions](../../docs/Predictions), which emphasize absolute forecasts for tasks like demand planning.
### Prerequisites [#prerequisites]
* An active project with a Dataset and trained Model.
* Access to the Simulations section (team role-dependent; see [Permissions and Roles](../../docs/users/Permissions%20and%20Roles)).
### Step 1: Start a New Simulation [#step-1-start-a-new-simulation]
Navigate to Simulations in the side menu and click "New Simulation."
### Step 2: Configure Basic Settings [#step-2-configure-basic-settings]
1. **Name (Optional):** Enter a descriptive name, or let Alviss AI generate one.
2. **Modeling Combination:** Select from available options.
3. **Advanced Options (If Available):** Choose a specific model and dataset.
4. **Date Range:** Set the simulation period.
### Step 3: Select Variables [#step-3-select-variables]
Choose variables to modify (e.g., media channels). Unselected ones use dataset defaults.
For this example, select all media-related variables.
### Step 4: Modify Scenario and Baseline [#step-4-modify-scenario-and-baseline]
Use the editor to define values:
* For Baseline: Use quick actions to set all to "Zero."
If warnings appear (e.g., for "always-on" channels like search), resolve by:
* Enabling out-of-bounds values.
* Correcting via "Keep," "Deform," or "Enforce Bounds."
* For Scenario: Set to "Max" per time point.
Fine-tune as needed:
* Adjust patterns (Historical, Constant, Custom).
* Scale additively or multiplicatively.
* Drag points on graphs for custom edits.
* Use per-variable buttons to shift by percentage, reset, or load from other periods.
### Step 5: Run and Review [#step-5-run-and-review]
Click "Create Simulation." It processes in the background.
Once ready, explore results:
* **Tabs:** Scenario, Baseline, Difference (Scenario - Baseline).
* **Visuals:** Total Effect, Product Over Time, Cumulative Product.
* **Tools:** Switch to tables, toggle uncertainty, apply filters.
In this media impact example, the Difference tab reveals incremental sales from max vs. zero spend. Experiment with variations for deeper insights!
For conceptual details, refer to [Simulations](../../docs/Simulations). Next, try [Optimizations](Run%20an%20Optimization) or [Predictions](Run%20a%20Prediction).
# Run An Optimization
Having completed:
1. [Create Dataset](Create%20Dataset)
2. [Building Your First Model](Building%20Your%20First%20Model)
you are now ready to run an Optimization. This tutorial guides you through using the Optimization feature to automatically determine the best variable settings—such as media budgets—for achieving your goals, like maximizing sales while adhering to constraints. Optimizations save time over manual adjustments in [Simulations](Run%20a%20Simulation) or [Predictions](Run%20a%20Prediction) by algorithmically tuning variables based on your models and dataset.
If you're focused on "what-if" comparisons, check out [Run a Simulation](Run%20a%20Simulation). For absolute forecasts, see [Run a Prediction](Run%20a%20Prediction).
### Prerequisites [#prerequisites]
* An active project with a Dataset and trained Model.
* Access to the Optimizations section (team role-dependent; see [Permissions and Roles](../../docs/users/Permissions%20and%20Roles)).
### Step 1: Start a New Optimization [#step-1-start-a-new-optimization]
Navigate to Optimizations in the side menu and click "New Optimization."
Set the basic configurations:
1. **Name (Optional):** Enter a descriptive name, or let Alviss AI generate one.
2. **Modeling Combination:** Select from available options.
3. **Advanced Options (If Available):** Choose a specific model and dataset.
### Step 2: Set Date Range [#step-2-set-date-range]
Define the optimization period, including optional pre- and post-periods for greater accuracy:
* **Pre-period:** Accounts for prior data influencing the start (e.g., carry-over from previous media investments).
* **Post-period:** Captures lingering effects after the period (e.g., adstock on future KPIs).
Example: Optimize over the next quarter, with a 1-month pre-period and 1-month post-period.
### Step 3: Select Mode [#step-3-select-mode]
Choose between:
* **Dynamic Optimization:** Automatically maximizes or minimizes your target KPI (e.g., maximize revenue).
* **Goal-Driven Optimization:** Aims for a specific target value, either absolute (e.g., exactly 10,000 sales) or relative (e.g., 20% more sales than baseline).
For this example, we'll use **Dynamic Optimization** to maximize sales by optimizing media spend.
### Step 4: Define Target [#step-4-define-target]
Select your KPI (e.g., sales or revenue).
* For Dynamic: Choose "Maximize" or "Minimize."
* For Goal-Driven: Set the goal value and specify absolute or relative.
In our example: Maximize sales.
### Step 5: Select Optimization Variables [#step-5-select-optimization-variables]
Choose variables to adjust (e.g., media channels like TV or digital ads). Unselected variables retain their dataset values.
For this tutorial, select all media-related variables.
Variables like media often have carry-over effects—consider including pre- and post-periods to account for them.
### Step 6: Add Constraints [#step-6-add-constraints]
Set sum-based constraints over the time period using `>`, `<`, or = operators. Group multiple variables if needed (e.g., total media budget ≤ \$100,000).
Example: Set total media spend ≤ 500,000 to enforce a budget cap.
Constraints are highly flexible and can be combined for scenarios like:
* Minimum spend across several channels.
* Front-loading a campaign.
### Step 7: Set Boundary Constraints (Optional) [#step-7-set-boundary-constraints-optional]
To prevent extreme values, apply per-time-point boundaries. If you want to stay close to historical limits, you can skip this step.
Options include:
* **Max:** Upper limit (e.g., \$5,000 per day on TV).
* **Min:** Lower limit (e.g., \$0).
* **Threshold Max:** If above the threshold, jump to Max (for step functions; requires Max to be set, with threshold \< Max).
* **Threshold Min:** If below the threshold, jump to Min (requires Min to be set, with threshold > Min).
### Step 8: Set Directions (Goal-Driven Only, Optional) [#step-8-set-directions-goal-driven-only-optional]
For Goal-Driven mode, specify desired trends for variables while hitting the target:
* **Minimize:** Reduce the variable as much as possible (e.g., minimize media spend to achieve the goal).
* **Maximize:** Increase it.
* **Neutral:** No preference (or leave unset).
Skip this for Dynamic mode.
### Step 9: Run and Review [#step-9-run-and-review]
Click "Submit" to run the optimization in the background. You'll be redirected to the optimization's detail page to monitor progress.
Once complete, review the results, which include both the optimized scenario and a baseline simulation using default dataset values for comparison:
* **Optimized Values:** Recommended settings for each variable.
* **Outcome Analysis:** KPI improvements vs. baseline, with graphs for totals, time-series trends, and cumulative effects.
* **Tools:** Toggle between graphs and tables, enable uncertainty visualization.
For conceptual details, refer to [Optimizations](../../docs/Optimizations).
# Getting Started
## Create a Project [#create-a-project]
When creating a project, you'll choose a name and decide on the fundamental data granularity. This granularity is crucial and cannot be changed later.
All projects you create within a team are automatically available to all team members. Learn how to create a [project](../../docs/Projects).
## Format Data [#format-data]
Your data files must comply with the platform's data specifications and match the granularity chosen during project creation.
Since your data might come from various sources, it's advisable to have a data professional verify the data and setup. Detailed guidelines can be found in the [Data Specification](../../docs/Data).
## Upload Data [#upload-data]
Once your data is correctly formatted and approved by relevant stakeholders, you can upload it to the platform. The platform will notify you immediately of any inconsistencies during the upload process. For more detailed instructions, go [here](../../docs/Data/Files).
## Create Dataset [#create-dataset]
After uploading, combine the chosen files into a [Dataset](../../docs/Data/Datasets) to use it for creating models, simulations, and predictions. Learn how to create and [activate](../../docs/Data/Datasets) a dataset.
## Inspect the data [#inspect-the-data]
With your dataset created and activated, visualize it in the [Activities](../../docs/Activities) dashboard. Inspecting the data ensures everything is correct before you proceed to model building.
## Build models [#build-models]
Next, create models to gain insights and run [Attributions](../../docs/Attributions), [Simulations](../../docs/Simulations) and [Predictions](../../docs/Predictions). The [Basic Model Builder](../../docs/Models/Basic%20Model%20Builder) is a great way to start. If you need more flexibility when building your models,
have a look at the [Advanced Model Builder](../../docs/Models/Advanced%20Model%20Builder).
## Get insights [#get-insights]
Once your models are trained, explore the insights they provide:
* **[Attributions](../../docs/Attributions):** Measure the impact of various variables on your KPIs.
* **[Simulations](../../docs/Simulations):** Experiment with "what if" scenarios to see how changes, such as increased marketing investments, would impact your KPIs.
* **[Predictions](../../docs/Predictions):** Forecast future sales based on changes to certain variables.
* **[Optimizations](../../docs/Optimizations):** Determine optimal investments tailored to your business targets and constraints.
* **[Response Curves](../../docs/Response%20Curves):** Visualize how specific variables affect your KPIs.
## Create Attributionset [#create-attributionset]
After running the Attributions, combine them into an [Attributions Set](../../docs/Attributions) to visualize the insights in the [Effect](../../docs/Effect) dashboard.
# Business Sanity
After [evaluating model fit](Evaluating%20Model%20Fit), it's critical to assess **business sanity**—the practical, real-world plausibility of your model's outputs. In Marketing Mix Modeling (MMM), even a model with exceptional fit (e.g., high R² or low MAPE) can be unreliable if it lacks business sanity. This often arises because key business drivers might be missing from the data, leading to unrealistic attributions or predictions. Prioritizing business sanity ensures your insights align with domain knowledge and support actionable decisions.
This tutorial explains what business sanity entails, how to inspect it using attributions, and steps to refine your model for better realism. By the end, you'll be equipped to validate models beyond mere statistical fit, enhancing their value for simulations, predictions, and optimizations.
## What is Business Sanity? [#what-is-business-sanity]
Business sanity refers to the logical consistency of model outputs with business expectations and industry norms. It goes beyond metrics like R² by questioning whether the results "make sense" in context. Key aspects to check include:
* **ROI Scale for Marketing:** Is the return on investment (ROI) for marketing activities realistic? For example, an ROI of 50x might be implausible for most channels.
* **ROI Spread Across Channels:** Does the distribution of ROI among media channels (e.g., TV vs. digital) reflect expected variations, without extreme outliers?
* **Variable Impact Signs:** Do variables affect KPIs in the expected direction? For instance, increased marketing spend should generally boost sales (positive effect), not reduce them.
* **Importance of Variable Groups:** Is the relative contribution of groups appropriate? Weather might influence seasonal products, but it shouldn't explain over 30% of sales variance in non-weather-sensitive industries.
These criteria vary by business, product, or market. What's reasonable for high-margin tech products might not apply to low-margin retail. Understanding your specific context—through stakeholder input or historical benchmarks—is essential for effective evaluation.
## Inspecting Business Sanity with Attributions [#inspecting-business-sanity-with-attributions]
The most effective way to check business sanity is via the **Attribution** tab on your model's details page. Attributions quantify the impact of variables on KPIs, using the same data the model was trained on. In most cases, an attribution is automatically generated; if not, create one by navigating to the tab and following the prompts (see [Attributions](../../docs/Attributions) for details).
1. Go to **Models** in the side menu.
2. Select your model and switch to the **Attribution** tab.
Focus on variable-specific sub-tabs (e.g., Media, Distribution) for targeted analysis. For example, to validate media learnings:
* Navigate to the **Media** sub-tab.
* Examine the **Attribution of Effects** plot.
This visualization breaks down media channels, showing:
* **Investment:** Total spend per channel.
* **Effect:** Attributed impact on the KPI (e.g., incremental sales).
* **Cost per Effect:** Efficiency metric (lower is better for cost-effectiveness).
* **ROI:** Return per unit invested (e.g., revenue generated per dollar spent).
Interpret these to spot issues. In the example above, the total media ROI is 24x, with one channel nearing 50x—this might be unrealistically high for many businesses, signaling a need for adjustment.
Use [filtering](../../docs/Filtering) to drill down by time periods, regions, or products for more granular sanity checks.
Repeat this process for other variable groups (e.g., Brand, Competitor Media) to ensure holistic sanity. Compare against business benchmarks—e.g., if historical ROI averages 5-10x, deviations warrant scrutiny.
## Refining the Model for Better Sanity [#refining-the-model-for-better-sanity]
If business sanity issues arise, refine the model without starting over. Common fixes include adjusting priors to enforce realistic behaviors.
1. On the model details page, select **Actions > Modify Model (High Level)**.
2. Use a node like the **SimulationEffect** node to impose stronger priors on key metrics.
* For the high ROI example, set a prior constraining media ROI to a more plausible range (e.g., 5-15x).
3. Submit the changes—the platform will refit the model incorporating these constraints.
4. Inspect the Attribution tab for the new model to verify improvements.
Apply similar refinements for other issues:
* **Wrong Sign:** Enforce positive/negative influences via variable group settings.
* **Over-Attributed Groups:** Adjust effect priors to redistribute importance (e.g., cap weather at 10%).
* **Missing Drivers:** If sanity reveals gaps (e.g., unexplained variance), extend your [Dataset](../../docs/Data/Datasets) with additional files like [Distribution](../../docs/Data/Files/Distribution) or [Brand](../../docs/Data/Files/Brand), then refit.
Over-constraining can harm fit—balance sanity with statistical performance.
## Best Practices for Business Sanity [#best-practices-for-business-sanity]
* Involve stakeholders early: Share attribution plots in team settings for collaborative validation.
* Benchmark iteratively: Compare sanity across model versions using notes or the [Projects](../../docs/Projects) structure.
* Document thresholds: Define acceptable ranges (e.g., ROI 3-20x) per project for consistency.
* Combine with fit: Always check sanity after confirming [convergance](Convergance.md) and [evaluating model fit](Evaluating%20Model%20Fit.md).
Ensuring business sanity transforms your models from statistically sound to practically useful, driving confident decisions in marketing and beyond. This completes the business sanity tutorial. Next in the series: Running Simulations and Predictions. For more, explore [Attributions](../../docs/Attributions). Keep validating!
# Convergance
After [building your first model](../Getting%20Started/Building%20Your%20First%20Model.md), it's essential to verify that the model has trained effectively. A key aspect of this is checking for **convergence**—ensuring the model's learning process stabilizes and reaches an optimal state. In Alviss AI, models typically converge reliably with default settings, making this a rare issue. However, it can occur with very complex models or when adjusting advanced parameters like `epochs` during training submission.
This tutorial guides you through inspecting convergence using the model's Metrics tab, interpreting key metrics, and troubleshooting if needed. Ensuring convergence leads to more accurate insights for marketing optimization, KPI impact analysis, and data-driven decisions—core strengths of Alviss AI's unified measurement platform.
## Understanding Model Convergence [#understanding-model-convergence]
Convergence happens when the model's training loss decreases to a minimal value and stabilizes with minimal fluctuations. This indicates the model has learned effectively from your data without overfitting or underfitting. Poor convergence might result in unreliable predictions, simulations, or attributions, affecting your ability to quantify commercial drivers like media investments or pricing strategies.
In Alviss AI, you can monitor convergence post-training via visual metrics plotted against training epochs (iterations). If issues arise, simple adjustments can refine the process.
## Step 1: Accessing the Model Details Page [#step-1-accessing-the-model-details-page]
1. Navigate to **Models** in the side menu of your project.
2. Select the model you just trained (e.g., from the list, identified by its name or random ID).
3. On the model details page, switch to the **Metrics** tab.
This tab displays training progress through graphs of various metrics as functions of epochs.
## Step 2: Reviewing Key Metrics [#step-2-reviewing-key-metrics]
The Metrics tab provides a comprehensive view of training and evaluation performance. Focus on these metrics to assess convergence:
* **Train Loss**: The primary indicator of overall model fit during training.
* **Evaluation Loss**: Measures performance on holdout (evaluation) data to check generalization.
* **Performance Metrics per KPI**: Drill-down views for specific KPIs (e.g., sales, revenue).
* [R²](../../wiki/R%20Squared) (Coefficient of Determination): Measures how well the model explains variance (closer to 1 is better).
* [Mean Squared Error (MSE)](../../wiki/Mean%20Squared%20Error): Average squared difference between predicted and actual values (lower is better).
* [Root Mean Squared Error (RMSE)](../../wiki/Root%20Mean%20Squared%20Error) : Square root of MSE, in the same units as the KPI (lower is better).
* [Bayes R²](../../wiki/Bayes%20R%20squared): A Bayesian variant of R² for probabilistic models.
* [Mean Absolute Percentage Error (MAPE)](../../wiki/Mean%20Absolute%20Percentage%20Error): Average percentage error (lower is better).
* [Mean Absolute Error (MAE)](../../wiki/Mean%20Absolute%20Error): Average absolute difference (lower is better).
* [Weighted Mean Absolute Percentage Error (WMAPE)](../../wiki/Weighted%20Mean%20Absolute%20Percentage%20Error) : Weighted version of MAPE for imbalanced data.
All metrics are plotted over epochs, allowing you to spot trends.
These metrics align with Alviss AI's focus on holistic business modeling, helping you validate impacts on KPIs like sales or churn across commercial activities.
## Step 3: Checking Train Loss for Convergence [#step-3-checking-train-loss-for-convergence]
Start with the **Train Loss** graph:
* Look for a steady decline that plateaus at a low value with little variation.
* Ideal convergence: The line flattens, indicating the model has optimized its parameters.
If the Train Loss converges well, proceed to deeper analysis. If not, note the pattern for troubleshooting (see below).
## Step 4: Drilling Down into Performance Metrics [#step-4-drilling-down-into-performance-metrics]
Once Train Loss looks stable:
1. Select **Train** (data from your selected training periods) or **Eval** (holdout evaluation periods) views.
2. Examine per-KPI metrics (e.g., R², MAPE) over epochs.
3. Ensure these also decline/stabilize, confirming the model performs consistently across your data.
Use [filtering](../../docs/Filtering) in the Metrics tab if your model includes multiple combinations (e.g., by country or region) for targeted inspection.
## Troubleshooting Non-Convergence [#troubleshooting-non-convergence]
If metrics don't converge fully, identify the issue from the graphs and adjust:
* **Still Improving but Not Stabilized**:
* Pattern: Loss/metrics continue decreasing without plateauing.
* Solution: Increase training epochs to allow more iterations.
1. On the model details page, go to **Actions > Refit Model**.
2. This resumes training from the last checkpoint, saving time.
3. Submit with higher `epochs` (e.g., double the original value).
* **Unstable or Oscillating**:
* Pattern: Loss jumps erratically, indicating instability (e.g., due to high learning rates).
* Solution: Retrain from scratch with adjustments for smoother optimization.
1. Create a new model via **Models > New Model** (use the [Advanced Model Builder](../../docs/Models/Advanced%20Model%20Builder) for fine control).
2. Decrease **Learning Rate** (e.g., to 0.001 or lower) to make updates gentler.
3. Reduce **Gradient Clipping** (e.g., to 1.0) to prevent extreme gradient explosions.
4. Increase **Epochs** to give the model more time to stabilize.
5. Submit and monitor the new Metrics tab.
Complex models (e.g., with many variable groups or custom effects) may require these tweaks. Always validate data quality in [Activities](../../docs/Activities) first, as outliers can mimic convergence issues.
## Best Practices for Reliable Convergence [#best-practices-for-reliable-convergence]
* Stick to defaults initially, as Alviss AI's sensible presets promote convergence.
* For advanced users: Experiment in the [Advanced Model Builder](../../docs/Models/Advanced%20Model%20Builder), but test small changes.
* After fixes, re-run [Attributions](../../docs/Attributions) or [Simulations](../../docs/Simulations) to confirm improved insights.
* If issues persist, review your [Dataset](../../docs/Data/Datasets) for consistency or consult Alviss AI's hybrid/full service options for expert assistance.
By verifying convergence, you ensure your models deliver accurate, actionable insights—empowering better resource allocation and growth, as highlighted in Alviss AI's platform for marketing and business optimization.
This completes the convergence tutorial. Next in the series: Running Your First Attributions. For more on models, see the full [Models](../../docs/Models) documentation. If you have questions, explore the app at [https://app.alviss.io](https://app.alviss.io) or reach out via support.
# Evaluating Model Fit
Welcome back to the Alviss AI Getting Started series! After \[building your first model]\(../Getting Started/Building Your First Model.md) and [Convergance](Convergance.md), the next crucial step is assessing how well the model fits your data. Model fit involves comparing the model's predicted KPIs (e.g., sales or revenue) against the actual data, both in the training period (where the model learns) and the holdout period (unseen data for validation). A good fit ensures reliable insights for attributions, simulations, predictions, and optimizations.
This tutorial covers two main approaches to evaluate fit: reviewing performance metrics for a quick overview and visually inspecting prediction plots for deeper analysis. By mastering these, you'll identify strengths, weaknesses, and potential improvements in your models.
## Approach 1: Reviewing Performance Metrics [#approach-1-reviewing-performance-metrics]
The simplest way to gauge model fit is through the **Performance** tab on your model's details page. This tab provides quantitative metrics that summarize prediction accuracy without requiring manual inspection.
1. Navigate to **Models** in the side menu.
2. Select your model and switch to the **Performance** tab.
Here, you'll see a series of performance measurements calculated for both training and evaluation (holdout) data:
* [R² (Coefficient of Determination)](../../wiki/R%20Squared): Measures how well the model explains variance (closer to 1 is better).
* [Mean Squared Error (MSE)](../../wiki/Mean%20Squared%20Error): Average squared difference between predicted and actual values (lower is better).
* [Root Mean Squared Error (RMSE)](../../wiki/Root%20Mean%20Squared%20Error): Square root of MSE, in the same units as the KPI (lower is better).
* [Bayes R²](../../wiki/Bayes%20R%20squared): A Bayesian variant of R² for probabilistic models.
* [Mean Absolute Percentage Error (MAPE)](../../wiki/Mean%20Absolute%20Percentage%20Error): Average percentage error (lower is better).
* [Mean Absolute Error (MAE)](../../wiki/Mean%20Absolute%20Error): Average absolute difference (lower is better).
* [Weighted Mean Absolute Percentage Error (WMAPE)](../../wiki/Weighted%20Mean%20Absolute%20Percentage%20Error): Weighted version of MAPE for imbalanced data.
The most commonly referenced metrics are **R²**, **Bayes R²**, and **MAPE** because they are scale-independent—unaffected by the magnitude of your KPI. Aim for R² and Bayes R² close to 1 (indicating strong explanatory power) and MAPE close to 0 (indicating low relative error).
Compare metrics between training and evaluation data. Similar values suggest good generalization; large gaps may indicate overfitting (great on training, poor on holdout) or underfitting (poor overall).
These metrics offer a quick benchmark for comparing models—e.g., testing iterations with different variable groups. However, they don't reveal *why* the fit is good or bad; for that, turn to visual inspection.
## Approach 2: Inspecting Fit (Prediction) vs. Actual Data [#approach-2-inspecting-fit-prediction-vs-actual-data]
For a more nuanced evaluation, examine the **Fit (prediction) vs actual data** plot in the model's details page (often under the Performance or Metrics tab). This visual comparison requires some experience but uncovers actionable insights that metrics alone miss.
Key questions to ask while reviewing the plot:
* **How well does it predict overall?** Look for close alignment between the predicted line (model output) and actual data points. Tight overlap indicates a strong fit.
* **Are there any outliers the model fails to capture?** Identify spikes or dips in actual data not mirrored in predictions. These could stem from real-world events (e.g., promotions or disruptions) needing investigation.
* **Are there systematic issues?** Check for patterns like consistent under-prediction in certain periods (e.g., holidays) or over-prediction in low-activity times, suggesting model limitations.
Toggle between training and holdout views to ensure the fit holds across both. Use [filtering](../../docs/Filtering) to zoom in on specific combinations (e.g., by country or product).
## Using Insights to Improve Your Model [#using-insights-to-improve-your-model]
Performance metrics provide a fast way to rank models, but studying the fit plot enables targeted enhancements:
* **Handling Outliers:** If the model misses anomalies, revisit your raw data in the [Activities](../../docs/Activities) dashboard. Explain them by adding flexibility—e.g., include [Events](../../docs/Data/Files/Events) variables or refine groupings.
* **Addressing Poor Fit Areas:** If predictions lag in specific segments, consider expanding inputs. A basic model with only seasonality and [Media](../../docs/Data/Files/Media) might underperform; try adding [Distribution](../../docs/Data/Files/Distribution), [Brand](../../docs/Data/Files/Brand), or [Macro](../../docs/Data/Files/Macro) variables for better capture without sacrificing business sanity.
* **Iterate Efficiently:** Use **Actions > Modify Model (High Level)** for quick tweaks by opening the model in the [Advanced Model Builder](../../docs/Models/Advanced%20Model%20Builder).
A "perfect" fit (e.g., R² = 1) on training data might signal overfitting—always validate on holdout. Balance fit with interpretability for real-world applications like marketing optimization.
## Best Practices for Model Fit Evaluation [#best-practices-for-model-fit-evaluation]
* Start with metrics for a high-level check, then dive into plots for diagnostics.
* Document findings in model notes for team collaboration.
* Benchmark against baselines (e.g., simple trend models) to quantify improvements.
* Re-evaluate fit after dataset extensions or refits to ensure ongoing quality.
A well-fitted model unlocks Alviss AI's full potential, delivering accurate attributions and forecasts. This completes the model fit tutorial. Next in the series: Running Your First Attributions. For deeper dives, explore the [Models](../../docs/Models). Keep refining!
# Inspect Model
Here we will cover how to actually inspect the model.
# Bayes R Squared
Bayes R² is a Bayesian adaptation of the traditional R², tailored for probabilistic models where uncertainty in predictions is explicitly modeled. It estimates the proportion of variance explained by the model while incorporating posterior distributions, making it robust for complex scenarios with stochastic elements. Bayes R² highlights the model's explanatory power under uncertainty, with values near 1 indicating strong fit, ideal for validating models in probabilistic frameworks.
The formula for Bayes R², as proposed by Gelman et al., is typically computed as:
$$
R^2 = \frac{Var(\hat{y})}{Var(\hat{y}) + Var(\epsilon)}
$$
Here,$Var(\hat{y})$ is the variance of the fitted (predicted) values, and $Var(\epsilon)$ is the variance of the residuals. In Bayesian contexts, this is evaluated over posterior samples, often taking the median for a point estimate.
This metric addresses limitations of classical R² in Bayesian settings by accounting for parameter uncertainty, ensuring more reliable insights. For instance, in analyzing feature influences, Bayes R² provides a nuanced view of explanatory power under variability.
Bayes R² facilitates assessments of model uncertainty, enhancing decision-making. However, it requires computational resources for posterior sampling, so use it judiciously with large datasets.
A key advantage is its handling of overfitting risks in hierarchical models. Compare it with standard R² to highlight Bayesian benefits.
# Bayesian Statistics
**Bayesian statistics** is a statistical approach that updates the probability of a hypothesis based on new data, incorporating prior knowledge (priors) and likelihoods to refine beliefs over time. In retail and marketing, it’s used to model uncertainty in variables like consumer behavior, channel performance, or economic factors, providing probabilistic insights rather than fixed estimates. Unlike traditional (frequentist) statistics, which rely solely on observed data for point estimates, Bayesian approaches incorporate priors to handle sparse data, quantify uncertainty, and enable more flexible modeling of complex relationships.
In Alviss AI, Bayesian statistics form the backbone of the platform's advanced modeling capabilities, enhancing Marketing Mix Modeling (MMM) with robust uncertainty estimation, prior integration, and scalability across datasets of varying sizes.
## Key Aspects [#key-aspects]
* **Priors and Posteriors:** Start with prior distributions (initial beliefs) and update them with data likelihoods to form posterior distributions, representing refined probabilities.
* **Uncertainty Quantification:** Outputs include credible intervals (e.g., quantiles) rather than confidence intervals, offering a direct probabilistic interpretation of results.
* **Hierarchical Modeling:** Supports multi-level structures, ideal for analyzing data across regions, products, or time periods with shared parameters.
* **Inference Methods:** Alviss employs techniques like variational inference for efficient computation, transforming sampling problems into optimizations for faster results.
## Integration with Alviss AI [#integration-with-alviss-ai]
Alviss AI leverages Bayesian statistics throughout its workflow to deliver reliable, data-driven insights:
* **Model Building:** In the \[Basic Model Builder]\(../docs/Models/Basic Model Builder) and \[Advanced Model Builder]\(../docs/Models/Advanced Model Builder), Bayesian frameworks allow for domain knowledge integration via priors, enabling models with as little as a month's data while scaling to decades.
* **Uncertainty Estimation:** Provides quantiles in [Attributions](../docs/Attributions), [Simulations](../docs/Simulations), and [Predictions](../docs/Predictions), quantifying confidence in outcomes like incremental volume or mROI.
* **Holdout Tests and Validation:** Bayesian priors help regularize models during \[Holdout Tests]\(Hold Out Test), improving generalization and reliability.
* **Hierarchical Models:** Applied in cases like multi-country budget optimization, capturing shared effects across levels for holistic analysis.
For example, in MMM, Bayesian methods reveal not just average effects but distributions, showing how TV ads might boost search efficiency with associated uncertainty.
Bayesian approaches in Alviss excel with limited data by using informative priors, but always validate with domain expertise to avoid bias.
## Benefits [#benefits]
* **Handling Uncertainty:** Essential for marketing decisions under noise, providing ranges (e.g., 80% credible intervals) to inform risk-aware strategies.
* **Overfitting Prevention:** Priors act as regularizers, as highlighted in Alviss blog posts on overcoming overfitting in MMM.
* **Flexibility and Scalability:** Supports hybrid online-offline analysis, privacy-compliant modeling (no cookie dependency), and future-proofing against data changes.
* **Actionable Insights:** Enhances [Optimizations](../docs/Optimizations) by incorporating uncertainty, leading to robust media plans and budget allocations.
# Hold Out Test
Holdout tests in Alviss AI are a key validation feature integrated into the model building interface, allowing you to reserve a portion of your dataset for evaluating model performance on unseen data. By splitting your data into training and holdout periods, you can assess how well your models generalize, detect overfitting, and ensure reliable insights for attributions, simulations, and predictions.
Alviss AI supports multiple holdout sets for more robust validation, with visual representations of holdout areas to compare predicted versus actual outcomes.
Holdout periods should be selected based on your data's time series nature—typically, use recent data as holdout to simulate future performance. Ensure your dataset has sufficient observations to avoid underfitting.
## Benefits of Holdout Tests [#benefits-of-holdout-tests]
* **Improved Model Reliability:** Validate against unseen data to ensure your models perform well in real-world scenarios, reducing the risk of biased insights.
* **Overfitting Prevention:** Identify models that memorize training data but fail on holdouts, guiding refinements in the Advanced Builder.
* **Data-Driven Confidence:** Quantify model accuracy before deploying to Attributions, Simulations, or Predictions, supporting better business decisions.
* **Efficiency in Collaboration:** Shared holdout configurations within teams ensure consistent validation across projects.
By incorporating holdout tests, you enhance the trustworthiness of your AI models, aligning with Alviss AI's focus on scalable, accurate, and actionable decision-making. For advanced validation techniques, consider combining with cross-validation or exploring custom nodes in the graph editor.
# Last Click Attribution
**Last-click attribution** is a widely used but limited method in digital marketing analytics where the entire credit for a conversion or sale is assigned to the final user interaction (touchpoint) before the purchase. In Alviss AI, understanding last-click attribution helps highlight its shortcomings compared to more advanced techniques like Marketing Mix Modeling (MMM), which provide a holistic view of channel contributions.
### Key Challenges [#key-challenges]
* **Oversimplification of the Customer Journey:** It ignores earlier interactions that build awareness or influence decisions, leading to biased insights.
* **Overemphasis on Lower-Funnel Tactics:** Channels like paid search ads or direct website visits often receive full credit, while upper-funnel efforts (e.g., TV ads, social media, or display campaigns) are undervalued.
* **Skewed Resource Allocation:** This can result in underinvestment in broad-reach channels that drive initial interest, potentially harming long-term growth.
### How It Works [#how-it-works]
In last-click models, credit is given solely to the last touchpoint, such as:
* Clicking a paid ad
* Visiting a website
* Opening a marketing email
This simplicity makes it easy to implement with basic tracking tools, but it fails to capture multi-touch dynamics.
### Example [#example]
Imagine a customer sees a TV ad for a product, sparking interest. They later search online and click a paid search ad to complete the purchase. Under last-click attribution, the search ad gets 100% credit, disregarding the TV ad's role. In Alviss AI's MMM approach, models can account for these synergies, revealing how upper-funnel activities enhance lower-funnel efficiency.
# Marginal Return On Investment
**Marginal Return on Investment (mROI)** measures the additional revenue or profit generated per dollar spent on a specific marketing activity, such as coupons or in-store displays. It’s a refined versioun of ROI (Return on Investment), focusing on in.cremental gains rather than overall returns.
mROI is particularly useful for detecting diminishing returns—e.g., when additional promo spend yields minimal volume uplift.
### Benefits [#benefits]
* **Budget Optimization:** Identify high-mROI activities to reallocate resources, potentially increasing overall profitability.
* **Strategic Decision-Making:** Compare mROI across channels to prioritize upper-funnel vs. lower-funnel tactics, avoiding pitfalls like those in [Last Click Attribution](Last%20Click%20Attribution).
# Mean Absolute Error
Mean Absolute Error (MAE) provides a straightforward absolute measure of prediction accuracy, averaging the absolute differences between predicted and actual values without squaring. This makes MAE less sensitive to outliers than squared metrics, offering a robust evaluation for datasets with anomalies. MAE highlights the average magnitude of errors in the target's units, with lower values indicating precise fits.
The formula for MAE is:
$$
\text{MAE} = \frac{1}{n} \sum_{i=1}^n |y_i - \hat{y}_i|
$$
Here,$y_i$ represents actuals,$\hat{y}_i$ predictions, and$n$ the sample size, yielding an error in the variable's units.
MAE's interpretability shines in practical applications where average error directly translates to impact. Compare it with RMSE to balance outlier sensitivity.
A limitation is its lack of relative scaling, so pair with percentage metrics for comprehensive views. MAE is ideal for median-based optimizations.
# Mean Absolute Percentage Error
Mean Absolute Percentage Error (MAPE) offers a relative measure of model accuracy, expressing errors as percentages of actual values, which is intuitive for comparing performance across different scales or variables. It's especially useful for forecasting tasks where understanding proportional errors matters. Lower MAPE values (closer to 0%) signal high accuracy, and it highlights relative error magnitudes, making it suitable for imbalanced or varying-scale data.
The formula for MAPE is:
$$
\text{MAPE} = \frac{1}{n} \sum_{i=1}^n \left| \frac{y_i - \hat{y}_i}{y_i} \right| \times 100\%
$$
Where$y_i$ is the actual value,$\hat{y}_i$ the prediction, and$n$ the number of points. This averages the absolute relative errors, multiplied by 100 for percentage form.
MAPE excels in contexts like time-series forecasting, but caution is needed with near-zero actuals to avoid division issues—consider weighted alternatives. It aids in evaluating proportional fit, ensuring insights align with real-world scales.
Its scale-independence makes it versatile, though it can be asymmetric for over/under-predictions. MAPE simplifies reporting of relative performance.
# Mean Squared Error
Mean Squared Error (MSE) serves as a foundational metric for evaluating regression model performance, measuring the average squared difference between predicted and actual values. It's particularly sensitive to large errors due to the squaring operation, making it ideal for identifying models that perform poorly on outliers in the data. MSE highlights the magnitude of errors in a quadratic sense, which is beneficial for optimization processes where penalizing larger deviations is desired.
The standard formula for MSE is:
$$
\text{MSE} = \frac{1}{n} \sum_{i=1}^n (y_i - \hat{y}_i)^2
$$
Where$y_i$ is the actual value,$\hat{y}_i$ the predicted value, and$n$ the number of data points. This calculation emphasizes larger deviations, which is useful for improving accuracy on high-impact observations.
Interpreting MSE requires considering the scale of the target variable; a low MSE indicates tight predictions, but its absolute value depends on the data's magnitude. Compare training and validation MSE to detect overfitting, ensuring the model generalizes well to new data.
One limitation of MSE is its lack of intuitiveness compared to percentage-based metrics, but it pairs well with RMSE for unit-aligned insights. Tracking MSE reductions across model iterations can highlight improvements in handling various input features.
# R Squared
The R² metric, or Coefficient of Determination, is a key indicator of how well a regression model explains the variance in the target variable. It quantifies the proportion of the total variation in the observed data that is accounted for by the model's predictions. Values range from 0 to 1, where a value closer to 1 signifies a strong fit, meaning the model captures most of the underlying patterns in the data. This metric highlights the model's explanatory power, making it useful for assessing overall fit during model evaluation and comparison.
The formula for R² is:
$$
R^2 = 1 - \frac{\sum_{i=1}^n (y_i - \hat{y}_i)^2}{\sum_{i=1}^n (y_i - \bar{y})^2}
$$
Here, $y_i$ represents the actual observed values, $\hat{y}_i$ the predicted values, $\bar{y}$ the mean of the actual values, and $n$ the number of observations. This equation compares the residual sum of squares (numerator) to the total sum of squares (denominator), providing a normalized measure of fit.
When interpreting R², consider it alongside other metrics for a balanced view, as high R² alone doesn't guarantee no overfitting—especially in complex models. For instance, in predictive modeling, a high R² might confirm that input features effectively explain target variance, aiding data-driven insights. However, in datasets with high noise or multicollinearity, R² can be misleading, so cross-reference with validation metrics on unseen data.
R²'s strength lies in its interpretability, making it accessible for evaluating model performance. That said, for probabilistic models, consider complementing it with variants like Bayes R² to account for uncertainty.
# Root Mean Squared Error
Root Mean Squared Error (RMSE) extends MSE by taking its square root, providing an error metric in the same units as the target variable, which enhances interpretability. This makes RMSE invaluable for evaluating model accuracy on tangible outcomes, such as forecasting continuous values. Lower RMSE values indicate better predictive performance, and it highlights the average magnitude of errors while remaining sensitive to outliers.
The formula for RMSE is:
$$
\text{RMSE} = \sqrt{\frac{1}{n} \sum_{i=1}^n (y_i - \hat{y}_i)^2}
$$
In this equation,$y_i$ denotes actual observations,$\hat{y}_i$ predictions, and$n$ the sample size. By rooting the averaged squared errors, RMSE balances sensitivity to outliers with practical units.
RMSE shines in comparing models across similar scales, directly informing predictive reliability. For example, a lower RMSE might validate a model's handling of input features. However, like MSE, it's scale-dependent, so normalize comparisons when datasets vary.
Its drawback is penalizing large errors heavily, which might overemphasize rare events—mitigate this by combining with MAE for a robust evaluation. RMSE's unit alignment makes it particularly useful for real-world interpretation of model errors.
# Scenario
A **scenario** in Alviss AI refers to a user-defined set of conditions or variables used in simulations and predictions to model hypothetical situations and forecast their potential outcomes. It allows you to test "what-if" strategies by adjusting factors such as pricing, distribution, media investments, or other commercial drivers, and compare them against a baseline (e.g., current or zero-investment conditions).
### Key Aspects [#key-aspects]
* **Purpose:** Scenarios help evaluate the impact of changes on key performance indicators (KPIs) like sales, churn, or revenue, enabling data-driven decision-making and strategy optimization.
* **Usage in Features:**
* **Simulations:** Define a scenario (e.g., increasing media spend) and contrast it with a baseline to analyze differences in results, such as ROI or performance uplift.
* **Predictions:** Set specific values for variables over time to generate forecasts, supporting demand planning or sales optimization.
* **Benefits:** By exploring multiple scenarios, you can identify synergistic opportunities, reduce risks, and maximize business growth—potentially achieving 10-20% sales increases through tweaks like pricing adjustments.
For practical implementation, refer to the [Simulations](../docs/Simulations) and [Predictions](../docs/Predictions) sections in the documentation. Use the platform's filtering and visualization tools to refine and interpret scenario results effectively.
# Weighted Mean Absolute Percentage Error
Weighted Mean Absolute Percentage Error (WMAPE) refines MAPE by weighting errors based on actual values, addressing imbalances in datasets where some observations are more critical. This metric is valuable for skewed data, ensuring errors on important points influence the score more. Lower WMAPE signifies better weighted accuracy, highlighting proportional errors with emphasis on higher-magnitude instances.
The formula for WMAPE is:
$$
\text{WMAPE} = \frac{\sum_{i=1}^n |y_i - \hat{y}_i|}{\sum_{i=1}^n |y_i|}
$$
Often expressed as a percentage by multiplying by 100, where$y_i$ are actuals and$\hat{y}_i$ predictions, normalizing by the sum of absolutes for robustness.
WMAPE enhances forecasting reliability, particularly where high-stakes periods matter. It mitigates MAPE's issues with zeros or low values by aggregation.
WMAPE's focus on magnitude makes it ideal for volume-driven variables, complementing other metrics for holistic evaluation. However, it assumes actuals as weights—customize if alternative weighting is needed.
# Wiki
This is the main page for our wiki.
# Get Currencies (/api/info/get_currencies_info_currencies_get)
Get supported currencies.
## GET /api/info/currencies
Get Currencies
Get supported currencies.
```json
{
"tags": [
"Info"
],
"summary": "Get Currencies",
"description": "Get supported currencies.",
"operationId": "get_currencies_info_currencies_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"items": {
"properties": {
"currency_code": {
"type": "string",
"title": "Currency Code"
},
"symbol": {
"type": "string",
"title": "Symbol"
}
},
"type": "object",
"required": [
"currency_code",
"symbol"
],
"title": "Currency",
"description": "Schema for currency data."
},
"type": "array",
"title": "Response Get Currencies Info Currencies Get"
}
}
}
}
}
}
```
# Get External Macro Info (/api/info/get_external_macro_info_info_datasource_get)
Get external data source info.
This endpoint is used to get the information about the external data source.
## GET /api/info/datasource
Get External Macro Info
Get external data source info.
This endpoint is used to get the information about the external data source.
```json
{
"tags": [
"Info"
],
"summary": "Get External Macro Info",
"description": "Get external data source info.\n\nThis endpoint is used to get the information about the external data source.",
"operationId": "get_external_macro_info_info_datasource_get",
"parameters": [
{
"name": "dataset_name",
"in": "query",
"required": true,
"schema": {
"enum": [
"Macro",
"Weather"
],
"type": "string",
"title": "Dataset Name"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Data Formats (/api/info/get_data_formats_info_data_formats_get)
Get data formats.
## GET /api/info/data_formats
Get Data Formats
Get data formats.
```json
{
"tags": [
"Info"
],
"summary": "Get Data Formats",
"description": "Get data formats.",
"operationId": "get_data_formats_info_data_formats_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
```
# Get Dataupload Example (/api/data-uploads/get_dataupload_example_info_example_datauploads_get)
Get data file example from the data specification.
## GET /api/info/example/datauploads
Get Dataupload Example
Get data file example from the data specification.
```json
{
"tags": [
"Data Uploads"
],
"summary": "Get Dataupload Example",
"description": "Get data file example from the data specification.",
"operationId": "get_dataupload_example_info_example_datauploads_get",
"parameters": [
{
"name": "dataset_name",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra"
],
"title": "Dataset",
"description": "User upload datasets."
}
},
{
"name": "format",
"in": "query",
"required": false,
"schema": {
"default": "long",
"type": "string",
"enum": [
"wide",
"long"
],
"title": "TableFormat",
"description": "Table format enum."
}
},
{
"name": "filetype",
"in": "query",
"required": false,
"schema": {
"default": "csv",
"type": "string",
"enum": [
"csv",
"excel"
],
"title": "FileType",
"description": "File type enum."
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Datauploads (/api/data-uploads/list_datauploads_projects__team_id___project_id__datauploads_get)
Get list of data uploads.
This endpoint retrieves a paginated list of data uploads based on the provided
filters. It supports optional inclusion of related variables and combinations.
Parameters:
- filters : A list of filters to apply to the data uploads query.
The filters should be provided in JSON format. Example usage:
filters='{"DataSet.Models.SimulationJobs.Name" : [[ "contains", "SimName"]]}'
- sess (Session): The database session to use for the query.
- project: The project context required for the query.
## GET /api/projects/{team_id}/{project_id}/datauploads
List Datauploads
Get list of data uploads.
This endpoint retrieves a paginated list of data uploads based on the provided
filters. It supports optional inclusion of related variables and combinations.
Parameters:
- filters : A list of filters to apply to the data uploads query.
The filters should be provided in JSON format. Example usage:
filters='{"DataSet.Models.SimulationJobs.Name" : [[ "contains", "SimName"]]}'
- sess (Session): The database session to use for the query.
- project: The project context required for the query.
```json
{
"tags": [
"Data Uploads"
],
"summary": "List Datauploads",
"description": "Get list of data uploads.\n\nThis endpoint retrieves a paginated list of data uploads based on the provided\nfilters. It supports optional inclusion of related variables and combinations.\n\nParameters:\n- filters : A list of filters to apply to the data uploads query.\n The filters should be provided in JSON format. Example usage:\n filters='{\"DataSet.Models.SimulationJobs.Name\" : [[ \"contains\", \"SimName\"]]}'\n- sess (Session): The database session to use for the query.\n- project: The project context required for the query.",
"operationId": "list_datauploads_projects__team_id___project_id__datauploads_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"complete\"]]}'\n - By dataset name: filters='{\"DatasetName\": [[\"=\", \"Sales\"]]}'\n - By name: filters='{\"Name\": [[\"contains\", \"Q4\"]]}'\n - Recent imports: filters='{\"Date\": [[\">=\", \"2024-01-01\"]]}'\n - Sort by date: filters='{\"Date\": [[\"orderby\", \"desc\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"complete\"]]}'\n - By dataset name: filters='{\"DatasetName\": [[\"=\", \"Sales\"]]}'\n - By name: filters='{\"Name\": [[\"contains\", \"Q4\"]]}'\n - Recent imports: filters='{\"Date\": [[\">=\", \"2024-01-01\"]]}'\n - Sort by date: filters='{\"Date\": [[\"orderby\", \"desc\"]]}'\n "
},
{
"name": "with_variables",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"default": false,
"title": "With Variables"
}
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /data-imports/{IId})"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Import creation timestamp"
},
"DatasetName": {
"type": "string",
"title": "Datasetname",
"description": "Target dataset name where data will be imported"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the import"
},
"Status": {
"description": "Import state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"External": {
"type": "boolean",
"title": "External",
"description": "Whether data comes from external source (e.g., macro indicators)"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"UploadFilename": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Uploadfilename",
"description": "Original filename of uploaded file"
},
"ModellingCombinations": {
"anyOf": [
{
"items": {
"properties": {
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"Country",
"Region",
"Grouping"
],
"title": "ModellingCombinationForDataImport",
"description": "Schema for modelling combination for data import."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Modellingcombinations"
},
"Variable": {
"anyOf": [
{
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"Slug": {
"type": "string",
"title": "Slug"
},
"Type": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes",
"description": "Varaible Tyeps."
},
"Group": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups",
"description": "Vraible groups."
}
},
"type": "object",
"required": [
"IId",
"Name",
"Slug",
"Type",
"Group"
],
"title": "VariableRef",
"description": "Variable reference."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variable"
}
},
"type": "object",
"required": [
"IId",
"Date",
"DatasetName",
"Status",
"External"
],
"title": "DataImportVariables",
"description": "Data import with optional variables.",
"examples": [
{
"CreatorId": "user_123",
"DatasetName": "sales",
"Date": "2024-01-15T10:30:00",
"External": false,
"IId": 1,
"Name": "Q4 Sales Data",
"Note": "Monthly sales figures for Q4 2024",
"Status": "complete",
"UploadFilename": "sales_q4_2024.csv"
}
]
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[DataImportVariables]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Upload Data (/api/data-uploads/upload_data_projects__team_id___project_id__datauploads_post)
Upload a data file.
The file should be in CSV, Excel, or Gzip format.
## POST /api/projects/{team_id}/{project_id}/datauploads
Upload Data
Upload a data file.
The file should be in CSV, Excel, or Gzip format.
```json
{
"tags": [
"Data Uploads"
],
"summary": "Upload Data",
"description": "Upload a data file.\n\nThe file should be in CSV, Excel, or Gzip format.",
"operationId": "upload_data_projects__team_id___project_id__datauploads_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "dataset_name",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra"
],
"title": "Dataset",
"description": "User upload datasets."
}
},
{
"name": "name",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
}
},
{
"name": "note",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note"
}
},
{
"name": "prefix",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix"
}
},
{
"name": "filename",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Filename"
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"properties": {
"file": {
"type": "string",
"contentMediaType": "application/octet-stream",
"title": "File",
"description": "The file to upload. Only .csv, .xls, .xlsx, .xlsb is supported or or gzip file containing one supported file (.gz)"
}
},
"type": "object",
"required": [
"file"
],
"title": "Body_upload_data_projects__team_id___project_id__datauploads_post"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Bulk Delete Datauploads (/api/data-uploads/bulk_delete_datauploads_projects__team_id___project_id__datauploads_delete)
Bulk delete data uploads matching the given filters.
Marks all matching uploads for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
Uploads used in an active dataset, model, or attribution set are excluded.
## DELETE /api/projects/{team_id}/{project_id}/datauploads
Bulk Delete Datauploads
Bulk delete data uploads matching the given filters.
Marks all matching uploads for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
Uploads used in an active dataset, model, or attribution set are excluded.
```json
{
"tags": [
"Data Uploads"
],
"summary": "Bulk Delete Datauploads",
"description": "Bulk delete data uploads matching the given filters.\n\nMarks all matching uploads for deletion and publishes delete messages to\nRabbitMQ concurrently in the background via a single DB round-trip each.\nUploads used in an active dataset, model, or attribution set are excluded.",
"operationId": "bulk_delete_datauploads_projects__team_id___project_id__datauploads_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /datauploads.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"complete\"]]}'\n - By name: filters='{\"Name\": [[\"contains\", \"Q4\"]]}'\n - By date: filters='{\"Date\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /datauploads.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"complete\"]]}'\n - By name: filters='{\"Name\": [[\"contains\", \"Q4\"]]}'\n - By date: filters='{\"Date\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n "
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Dataupload (/api/data-uploads/get_dataupload_projects__team_id___project_id__datauploads__item_id__get)
Get a dataupload info.
## GET /api/projects/{team_id}/{project_id}/datauploads/{item_id}
Get Dataupload
Get a dataupload info.
```json
{
"tags": [
"Data Uploads"
],
"summary": "Get Dataupload",
"description": "Get a dataupload info.",
"operationId": "get_dataupload_projects__team_id___project_id__datauploads__item_id__get",
"parameters": [
{
"name": "item_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Data upload scoped id",
"title": "Item Id"
},
"description": "Data upload scoped id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /data-imports/{IId})"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Import creation timestamp"
},
"DatasetName": {
"type": "string",
"title": "Datasetname",
"description": "Target dataset name where data will be imported"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the import"
},
"Status": {
"description": "Import state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"External": {
"type": "boolean",
"title": "External",
"description": "Whether data comes from external source (e.g., macro indicators)"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"UploadFilename": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Uploadfilename",
"description": "Original filename of uploaded file"
},
"UploadProgress": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Uploadprogress"
}
},
"type": "object",
"required": [
"IId",
"Date",
"DatasetName",
"Status",
"External"
],
"title": "RunningDataImport",
"description": "Reference schema for running data import.",
"examples": [
{
"CreatorId": "user_123",
"DatasetName": "sales",
"Date": "2024-01-15T10:30:00",
"External": false,
"IId": 1,
"Name": "Q4 Sales Data",
"Note": "Monthly sales figures for Q4 2024",
"Status": "complete",
"UploadFilename": "sales_q4_2024.csv"
}
]
},
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /data-imports/{IId})"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Import creation timestamp"
},
"DatasetName": {
"type": "string",
"title": "Datasetname",
"description": "Target dataset name where data will be imported"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the import"
},
"Status": {
"description": "Import state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"External": {
"type": "boolean",
"title": "External",
"description": "Whether data comes from external source (e.g., macro indicators)"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"UploadFilename": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Uploadfilename",
"description": "Original filename of uploaded file"
},
"ModellingCombinations": {
"anyOf": [
{
"items": {
"properties": {
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"Country",
"Region",
"Grouping"
],
"title": "ModellingCombinationForDataImport",
"description": "Schema for modelling combination for data import."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Modellingcombinations"
}
},
"type": "object",
"required": [
"IId",
"Date",
"DatasetName",
"Status",
"External"
],
"title": "DataImportCombs",
"description": "Data import with combs.",
"examples": [
{
"CreatorId": "user_123",
"DatasetName": "sales",
"Date": "2024-01-15T10:30:00",
"External": false,
"IId": 1,
"Name": "Q4 Sales Data",
"Note": "Monthly sales figures for Q4 2024",
"Status": "complete",
"UploadFilename": "sales_q4_2024.csv"
}
]
}
],
"title": "Response Get Dataupload Projects Team Id Project Id Datauploads Item Id Get"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Dataupload (/api/data-uploads/update_dataupload_projects__team_id___project_id__datauploads__item_id__patch)
Update a dataupload's note.
## PATCH /api/projects/{team_id}/{project_id}/datauploads/{item_id}
Update Dataupload
Update a dataupload's note.
```json
{
"tags": [
"Data Uploads"
],
"summary": "Update Dataupload",
"description": "Update a dataupload's note.",
"operationId": "update_dataupload_projects__team_id___project_id__datauploads__item_id__patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "item_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Data upload scoped id",
"title": "Item Id"
},
"description": "Data upload scoped id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Description for the model/dataset"
}
},
"type": "object",
"title": "DataUploadsUpdate",
"description": "Schema for updating data uploads.",
"examples": [
{
"Name": "Updated Sales Data Q4",
"Note": "Corrected version with December figures"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /data-imports/{IId})"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Import creation timestamp"
},
"DatasetName": {
"type": "string",
"title": "Datasetname",
"description": "Target dataset name where data will be imported"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the import"
},
"Status": {
"description": "Import state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"External": {
"type": "boolean",
"title": "External",
"description": "Whether data comes from external source (e.g., macro indicators)"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"UploadFilename": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Uploadfilename",
"description": "Original filename of uploaded file"
}
},
"type": "object",
"required": [
"IId",
"Date",
"DatasetName",
"Status",
"External"
],
"title": "DataImport",
"description": "Response schema for data import jobs.",
"examples": [
{
"CreatorId": "user_123",
"DatasetName": "sales",
"Date": "2024-01-15T10:30:00",
"External": false,
"IId": 1,
"Name": "Q4 Sales Data",
"Note": "Monthly sales figures for Q4 2024",
"Status": "complete",
"UploadFilename": "sales_q4_2024.csv"
}
]
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Dataupload (/api/data-uploads/delete_dataupload_projects__team_id___project_id__datauploads__item_id__delete)
Delete a dataupload file.
## DELETE /api/projects/{team_id}/{project_id}/datauploads/{item_id}
Delete Dataupload
Delete a dataupload file.
```json
{
"tags": [
"Data Uploads"
],
"summary": "Delete Dataupload",
"description": "Delete a dataupload file.",
"operationId": "delete_dataupload_projects__team_id___project_id__datauploads__item_id__delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "item_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Data upload scoped id",
"title": "Item Id"
},
"description": "Data upload scoped id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get External Dataupload Indicators (/api/data-uploads/get_external_dataupload_indicators_projects__team_id___project_id__datauploads__item_id__external_indicators_get)
Get list of indicators for external datasource per country.
## GET /api/projects/{team_id}/{project_id}/datauploads/{item_id}/external_indicators
Get External Dataupload Indicators
Get list of indicators for external datasource per country.
```json
{
"tags": [
"Data Uploads"
],
"summary": "Get External Dataupload Indicators",
"description": "Get list of indicators for external datasource per country.",
"operationId": "get_external_dataupload_indicators_projects__team_id___project_id__datauploads__item_id__external_indicators_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "item_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Data upload scoped id",
"title": "Item Id"
},
"description": "Data upload scoped id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"country": {
"type": "string",
"title": "Country"
},
"indicators": {
"items": {
"properties": {
"Indicator": {
"type": "string",
"title": "Indicator"
},
"StartDate": {
"type": "string",
"format": "date-time",
"title": "Startdate"
},
"EndDate": {
"type": "string",
"format": "date-time",
"title": "Enddate"
}
},
"type": "object",
"required": [
"Indicator",
"StartDate",
"EndDate"
],
"title": "_Indicator"
},
"type": "array",
"title": "Indicators"
}
},
"type": "object",
"required": [
"country",
"indicators"
],
"title": "CoutnryIndicatorDates",
"description": "External ataimport's countries indicators and dates."
},
"title": "Response Get External Dataupload Indicators Projects Team Id Project Id Datauploads Item Id External Indicators Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Dataupload Dates Min Max (/api/data-uploads/get_dataupload_dates_min_max_projects__team_id___project_id__datauploads__item_id__dates_min_max_get)
Get min and max data dates for a data upload.
## GET /api/projects/{team_id}/{project_id}/datauploads/{item_id}/dates_min_max
Get Dataupload Dates Min Max
Get min and max data dates for a data upload.
```json
{
"tags": [
"Data Uploads"
],
"summary": "Get Dataupload Dates Min Max",
"description": "Get min and max data dates for a data upload.",
"operationId": "get_dataupload_dates_min_max_projects__team_id___project_id__datauploads__item_id__dates_min_max_get",
"parameters": [
{
"name": "item_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Data upload scoped id",
"title": "Item Id"
},
"description": "Data upload scoped id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"min": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Min"
},
"max": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Max"
}
},
"type": "object",
"required": [
"min",
"max"
],
"title": "DateRange",
"description": "Min and max dates for a resource collection."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Downalod Dataupload (/api/data-uploads/downalod_dataupload_projects__team_id___project_id__datauploads__item_id__data_get)
Get a dataupload in csv format and would exclude auto-generated variables.
## GET /api/projects/{team_id}/{project_id}/datauploads/{item_id}/data
Downalod Dataupload
Get a dataupload in csv format and would exclude auto-generated variables.
```json
{
"tags": [
"Data Uploads"
],
"summary": "Downalod Dataupload",
"description": "Get a dataupload in csv format and would exclude auto-generated variables.",
"operationId": "downalod_dataupload_projects__team_id___project_id__datauploads__item_id__data_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "item_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Data upload scoped id",
"title": "Item Id"
},
"description": "Data upload scoped id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "output_format",
"in": "query",
"required": false,
"schema": {
"enum": [
"csv",
"parquet"
],
"type": "string",
"default": "csv",
"title": "Output Format"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Interpolated Upload (/api/data-uploads/download_interpolated_upload_projects__team_id___project_id__datauploads__item_id__interpolate_variable_data_get)
Download a dataimport interpolated variable as csv.
## GET /api/projects/{team_id}/{project_id}/datauploads/{item_id}/interpolate_variable_data
Download Interpolated Upload
Download a dataimport interpolated variable as csv.
```json
{
"tags": [
"Data Uploads"
],
"summary": "Download Interpolated Upload",
"description": "Download a dataimport interpolated variable as csv.",
"operationId": "download_interpolated_upload_projects__team_id___project_id__datauploads__item_id__interpolate_variable_data_get",
"parameters": [
{
"name": "item_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Data upload scoped id",
"title": "Item Id"
},
"description": "Data upload scoped id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "data_filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n Filter data rows by geographic or other attributes.\n\n Examples:\n - By country: filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - Multiple countries: filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By region: filters='{\"Region\": [[\"=\", \"northeast\"]]}'\n - By date: filters='{\"Date\": [[\">=\", \"2024-01-01\"]]}'\n ",
"title": "Data Filters"
},
"description": "\n Filter data rows by geographic or other attributes.\n\n Examples:\n - By country: filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - Multiple countries: filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By region: filters='{\"Region\": [[\"=\", \"northeast\"]]}'\n - By date: filters='{\"Date\": [[\">=\", \"2024-01-01\"]]}'\n "
},
{
"name": "start_date",
"in": "query",
"required": true,
"schema": {
"type": "string",
"format": "date-time",
"description": "Start date for extrapolated data. This parameter is only for extrapolation not to limit the data. To filter the data please pass it into data_filter",
"title": "Start Date"
},
"description": "Start date for extrapolated data. This parameter is only for extrapolation not to limit the data. To filter the data please pass it into data_filter"
},
{
"name": "end_date",
"in": "query",
"required": true,
"schema": {
"type": "string",
"format": "date-time",
"description": "End date for extrapolated data This parameter is only for extrapolation not to limit the data. To filter the data please pass it into data_filter",
"title": "End Date"
},
"description": "End date for extrapolated data This parameter is only for extrapolation not to limit the data. To filter the data please pass it into data_filter"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Interpolated Upload Query (/api/data-uploads/download_interpolated_upload_query_projects__team_id___project_id__datauploads__item_id__interpolate_variable_data_query_post)
Download dataimport interpolated variable — POST variant for large filter payloads.
## POST /api/projects/{team_id}/{project_id}/datauploads/{item_id}/interpolate_variable_data_query
Download Interpolated Upload Query
Download dataimport interpolated variable — POST variant for large filter payloads.
```json
{
"tags": [
"Data Uploads"
],
"summary": "Download Interpolated Upload Query",
"description": "Download dataimport interpolated variable — POST variant for large filter payloads.",
"operationId": "download_interpolated_upload_query_projects__team_id___project_id__datauploads__item_id__interpolate_variable_data_query_post",
"parameters": [
{
"name": "item_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Data upload scoped id",
"title": "Item Id"
},
"description": "Data upload scoped id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"data_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Data Filters"
},
"start_date": {
"type": "string",
"format": "date-time",
"title": "Start Date"
},
"end_date": {
"type": "string",
"format": "date-time",
"title": "End Date"
}
},
"type": "object",
"required": [
"start_date",
"end_date"
],
"title": "InterpolateUploadBody",
"description": "Request body for interpolated upload _query endpoint."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Projects (/api/projects/list_projects_projects__team_id__get)
List available projects.
## GET /api/projects/{team_id}
List Projects
List available projects.
```json
{
"tags": [
"Projects"
],
"summary": "List Projects",
"description": "List available projects.",
"operationId": "list_projects_projects__team_id__get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "sort",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Sort order, format 'field:(asc|desc)'. field ∈ {name, created, last_used} (legacy: Name, CreatedDate, LastUsedDate).",
"default": "created:asc",
"title": "Sort"
},
"description": "Sort order, format 'field:(asc|desc)'. field ∈ {name, created, last_used} (legacy: Name, CreatedDate, LastUsedDate)."
},
{
"name": "name",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter projects by name (case-insensitive partial match)",
"title": "Name"
},
"description": "Filter projects by name (case-insensitive partial match)"
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"slug": {
"type": "string",
"title": "Slug"
},
"periodicity": {
"type": "string",
"enum": [
"MINUTE",
"HOUR",
"DAY",
"WEEK",
"MONTH",
"QUARTER",
"YEAR"
],
"title": "Periodicity",
"description": "Schema for periodicity."
},
"currency_code": {
"type": "string",
"title": "Currency Code"
},
"created_date": {
"type": "string",
"format": "date-time",
"title": "Created Date"
},
"last_used_date": {
"type": "string",
"format": "date-time",
"title": "Last Used Date"
},
"variables_data_version": {
"type": "integer",
"title": "Variables Data Version",
"default": 0
},
"activity_dashboard_mode": {
"type": "string",
"enum": [
"EFFECTS",
"ACTIVE"
],
"title": "ActivityDasboardMode",
"description": "Type of activity dasboard."
},
"settings": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Settings"
},
"countries": {
"items": {
"type": "string"
},
"type": "array",
"title": "Countries"
},
"regions": {
"items": {
"type": "string"
},
"type": "array",
"title": "Regions"
},
"groupings": {
"items": {
"type": "string"
},
"type": "array",
"title": "Groupings"
},
"products": {
"items": {
"type": "string"
},
"type": "array",
"title": "Products"
},
"num_countries": {
"type": "integer",
"title": "Num Countries",
"default": 0
},
"num_regions": {
"type": "integer",
"title": "Num Regions",
"default": 0
},
"num_data_sources_uploaded": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Num Data Sources Uploaded"
},
"num_model_combinations_built": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Num Model Combinations Built"
},
"num_model_combinations": {
"type": "integer",
"title": "Num Model Combinations",
"default": 0
},
"active_models": {
"items": {
"properties": {
"country": {
"type": "string",
"title": "Country"
},
"region": {
"type": "string",
"title": "Region"
},
"grouping": {
"type": "string",
"title": "Grouping"
},
"targets": {
"type": "integer",
"title": "Targets"
},
"quality_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Quality Score"
}
},
"type": "object",
"required": [
"country",
"region",
"grouping",
"targets"
],
"title": "ActiveModelMetrics",
"description": "Per-active-model targets + quality score, one entry per Selected model."
},
"type": "array",
"title": "Active Models"
},
"active_dataset": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
{
"type": "null"
}
]
},
"latest_data_point_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Latest Data Point Date"
},
"latest_upload_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Latest Upload Date"
},
"latest_prediction_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Latest Prediction Date"
},
"total_media_spend": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Total Media Spend"
},
"total_sales": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Total Sales"
},
"avg_brand_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Avg Brand Value"
},
"latest_effect_roi": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Latest Effect Roi"
}
},
"type": "object",
"required": [
"Id",
"name",
"slug",
"periodicity",
"currency_code",
"created_date",
"last_used_date",
"activity_dashboard_mode"
],
"title": "Projects",
"description": "Schema for project response.",
"examples": [
{
"Id": 1,
"active_models": [
{
"country": "US",
"grouping": "all",
"quality_score": 0.92,
"region": "West",
"targets": 3
}
],
"activity_dashboard_mode": "ACTIVE",
"countries": [
"US",
"UK"
],
"created_date": "2024-01-15T10:30:00",
"currency_code": "USD",
"last_used_date": "2024-12-01T14:22:00",
"latest_effect_roi": 1.45,
"name": "Q4 Marketing Analysis",
"num_countries": 2,
"num_data_sources_uploaded": 3,
"periodicity": "WEEK",
"products": [
"ProductA",
"ProductB"
],
"regions": [
"West",
"East"
],
"slug": "q4-marketing-2024"
}
]
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[Projects]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Create Project (/api/projects/create_project_projects__team_id__post)
Create a new project.
## POST /api/projects/{team_id}
Create Project
Create a new project.
```json
{
"tags": [
"Projects"
],
"summary": "Create Project",
"description": "Create a new project.",
"operationId": "create_project_projects__team_id__post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"type": "string",
"maxLength": 30,
"minLength": 2,
"title": "Name",
"description": "name attribute for project"
},
"periodicity": {
"description": "Periodicity for project, must be capital letter.",
"type": "string",
"enum": [
"MINUTE",
"HOUR",
"DAY",
"WEEK",
"MONTH",
"QUARTER",
"YEAR"
],
"title": "Periodicity"
},
"currency_code": {
"type": "string",
"maxLength": 3,
"minLength": 3,
"title": "Currency Code",
"description": "Currency code for project, must be capital letter and follow ISO 4217, check `/info/currencies`.",
"one_of": [
"AED",
"AFN",
"ALL",
"AMD",
"ANG",
"AOA",
"ARS",
"AUD",
"AWG",
"AZN",
"BAM",
"BBD",
"BDT",
"BGN",
"BHD",
"BIF",
"BMD",
"BND",
"BOB",
"BRL",
"BSD",
"BTN",
"BWP",
"BYN",
"BZD",
"CAD",
"CDF",
"CHF",
"CLP",
"CNY",
"COP",
"CRC",
"CUC",
"CUP",
"CVE",
"CZK",
"DJF",
"DKK",
"DOP",
"DZD",
"EGP",
"ERN",
"ETB",
"EUR",
"FJD",
"FKP",
"GBP",
"GEL",
"GHS",
"GIP",
"GMD",
"GNF",
"GTQ",
"GYD",
"HKD",
"HNL",
"HRK",
"HTG",
"HUF",
"IDR",
"ILS",
"INR",
"IQD",
"IRR",
"ISK",
"JMD",
"JOD",
"JPY",
"KES",
"KGS",
"KHR",
"KMF",
"KPW",
"KRW",
"KWD",
"KYD",
"KZT",
"LAK",
"LBP",
"LKR",
"LRD",
"LSL",
"LYD",
"MAD",
"MDL",
"MGA",
"MKD",
"MMK",
"MNT",
"MOP",
"MRU",
"MUR",
"MVR",
"MWK",
"MXN",
"MYR",
"MZN",
"NAD",
"NGN",
"NIO",
"NOK",
"NPR",
"NZD",
"OMR",
"PAB",
"PEN",
"PGK",
"PHP",
"PKR",
"PLN",
"PYG",
"QAR",
"RON",
"RSD",
"RUB",
"RWF",
"SAR",
"SBD",
"SCR",
"SDG",
"SEK",
"SGD",
"SHP",
"SLL",
"SOS",
"SRD",
"SSP",
"STN",
"SVC",
"SYP",
"SZL",
"THB",
"TJS",
"TMT",
"TND",
"TOP",
"TRY",
"TTD",
"TWD",
"TZS",
"UAH",
"UGX",
"USD",
"UYU",
"UZS",
"VES",
"VND",
"VUV",
"WST",
"XAF",
"XCD",
"XOF",
"XPF",
"YER",
"ZAR",
"ZMW",
"ZWL"
]
},
"slug": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Slug",
"description": "slug for project"
}
},
"type": "object",
"required": [
"name",
"periodicity",
"currency_code"
],
"title": "ProjectsRequest",
"description": "Schema for project request body.",
"examples": [
{
"currency_code": "USD",
"name": "Q4 Marketing Analysis",
"periodicity": "WEEK",
"slug": "q4-marketing-2024"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"slug": {
"type": "string",
"title": "Slug"
},
"periodicity": {
"type": "string",
"enum": [
"MINUTE",
"HOUR",
"DAY",
"WEEK",
"MONTH",
"QUARTER",
"YEAR"
],
"title": "Periodicity",
"description": "Schema for periodicity."
},
"currency_code": {
"type": "string",
"title": "Currency Code"
},
"created_date": {
"type": "string",
"format": "date-time",
"title": "Created Date"
},
"last_used_date": {
"type": "string",
"format": "date-time",
"title": "Last Used Date"
},
"variables_data_version": {
"type": "integer",
"title": "Variables Data Version",
"default": 0
},
"activity_dashboard_mode": {
"type": "string",
"enum": [
"EFFECTS",
"ACTIVE"
],
"title": "ActivityDasboardMode",
"description": "Type of activity dasboard."
},
"settings": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Settings"
},
"countries": {
"items": {
"type": "string"
},
"type": "array",
"title": "Countries"
},
"regions": {
"items": {
"type": "string"
},
"type": "array",
"title": "Regions"
},
"groupings": {
"items": {
"type": "string"
},
"type": "array",
"title": "Groupings"
},
"products": {
"items": {
"type": "string"
},
"type": "array",
"title": "Products"
},
"num_countries": {
"type": "integer",
"title": "Num Countries",
"default": 0
},
"num_regions": {
"type": "integer",
"title": "Num Regions",
"default": 0
},
"num_data_sources_uploaded": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Num Data Sources Uploaded"
},
"num_model_combinations_built": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Num Model Combinations Built"
},
"num_model_combinations": {
"type": "integer",
"title": "Num Model Combinations",
"default": 0
},
"active_models": {
"items": {
"properties": {
"country": {
"type": "string",
"title": "Country"
},
"region": {
"type": "string",
"title": "Region"
},
"grouping": {
"type": "string",
"title": "Grouping"
},
"targets": {
"type": "integer",
"title": "Targets"
},
"quality_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Quality Score"
}
},
"type": "object",
"required": [
"country",
"region",
"grouping",
"targets"
],
"title": "ActiveModelMetrics",
"description": "Per-active-model targets + quality score, one entry per Selected model."
},
"type": "array",
"title": "Active Models"
},
"active_dataset": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
{
"type": "null"
}
]
},
"latest_data_point_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Latest Data Point Date"
},
"latest_upload_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Latest Upload Date"
},
"latest_prediction_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Latest Prediction Date"
},
"total_media_spend": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Total Media Spend"
},
"total_sales": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Total Sales"
},
"avg_brand_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Avg Brand Value"
},
"latest_effect_roi": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Latest Effect Roi"
}
},
"type": "object",
"required": [
"Id",
"name",
"slug",
"periodicity",
"currency_code",
"created_date",
"last_used_date",
"activity_dashboard_mode"
],
"title": "Projects",
"description": "Schema for project response.",
"examples": [
{
"Id": 1,
"active_models": [
{
"country": "US",
"grouping": "all",
"quality_score": 0.92,
"region": "West",
"targets": 3
}
],
"activity_dashboard_mode": "ACTIVE",
"countries": [
"US",
"UK"
],
"created_date": "2024-01-15T10:30:00",
"currency_code": "USD",
"last_used_date": "2024-12-01T14:22:00",
"latest_effect_roi": 1.45,
"name": "Q4 Marketing Analysis",
"num_countries": 2,
"num_data_sources_uploaded": 3,
"periodicity": "WEEK",
"products": [
"ProductA",
"ProductB"
],
"regions": [
"West",
"East"
],
"slug": "q4-marketing-2024"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Project (/api/projects/get_project_projects__team_id___project_id__get)
Get a project info.
## GET /api/projects/{team_id}/{project_id}
Get Project
Get a project info.
```json
{
"tags": [
"Projects"
],
"summary": "Get Project",
"description": "Get a project info.",
"operationId": "get_project_projects__team_id___project_id__get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"slug": {
"type": "string",
"title": "Slug"
},
"periodicity": {
"type": "string",
"enum": [
"MINUTE",
"HOUR",
"DAY",
"WEEK",
"MONTH",
"QUARTER",
"YEAR"
],
"title": "Periodicity",
"description": "Schema for periodicity."
},
"currency_code": {
"type": "string",
"title": "Currency Code"
},
"created_date": {
"type": "string",
"format": "date-time",
"title": "Created Date"
},
"last_used_date": {
"type": "string",
"format": "date-time",
"title": "Last Used Date"
},
"variables_data_version": {
"type": "integer",
"title": "Variables Data Version",
"default": 0
},
"activity_dashboard_mode": {
"type": "string",
"enum": [
"EFFECTS",
"ACTIVE"
],
"title": "ActivityDasboardMode",
"description": "Type of activity dasboard."
},
"settings": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Settings"
},
"countries": {
"items": {
"type": "string"
},
"type": "array",
"title": "Countries"
},
"regions": {
"items": {
"type": "string"
},
"type": "array",
"title": "Regions"
},
"groupings": {
"items": {
"type": "string"
},
"type": "array",
"title": "Groupings"
},
"products": {
"items": {
"type": "string"
},
"type": "array",
"title": "Products"
},
"num_countries": {
"type": "integer",
"title": "Num Countries",
"default": 0
},
"num_regions": {
"type": "integer",
"title": "Num Regions",
"default": 0
},
"num_data_sources_uploaded": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Num Data Sources Uploaded"
},
"num_model_combinations_built": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Num Model Combinations Built"
},
"num_model_combinations": {
"type": "integer",
"title": "Num Model Combinations",
"default": 0
},
"active_models": {
"items": {
"properties": {
"country": {
"type": "string",
"title": "Country"
},
"region": {
"type": "string",
"title": "Region"
},
"grouping": {
"type": "string",
"title": "Grouping"
},
"targets": {
"type": "integer",
"title": "Targets"
},
"quality_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Quality Score"
}
},
"type": "object",
"required": [
"country",
"region",
"grouping",
"targets"
],
"title": "ActiveModelMetrics",
"description": "Per-active-model targets + quality score, one entry per Selected model."
},
"type": "array",
"title": "Active Models"
},
"active_dataset": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
{
"type": "null"
}
]
},
"latest_data_point_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Latest Data Point Date"
},
"latest_upload_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Latest Upload Date"
},
"latest_prediction_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Latest Prediction Date"
},
"total_media_spend": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Total Media Spend"
},
"total_sales": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Total Sales"
},
"avg_brand_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Avg Brand Value"
},
"latest_effect_roi": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Latest Effect Roi"
}
},
"type": "object",
"required": [
"Id",
"name",
"slug",
"periodicity",
"currency_code",
"created_date",
"last_used_date",
"activity_dashboard_mode"
],
"title": "Projects",
"description": "Schema for project response.",
"examples": [
{
"Id": 1,
"active_models": [
{
"country": "US",
"grouping": "all",
"quality_score": 0.92,
"region": "West",
"targets": 3
}
],
"activity_dashboard_mode": "ACTIVE",
"countries": [
"US",
"UK"
],
"created_date": "2024-01-15T10:30:00",
"currency_code": "USD",
"last_used_date": "2024-12-01T14:22:00",
"latest_effect_roi": 1.45,
"name": "Q4 Marketing Analysis",
"num_countries": 2,
"num_data_sources_uploaded": 3,
"periodicity": "WEEK",
"products": [
"ProductA",
"ProductB"
],
"regions": [
"West",
"East"
],
"slug": "q4-marketing-2024"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Project (/api/projects/update_project_projects__team_id___project_id__patch)
Update a project.
## PATCH /api/projects/{team_id}/{project_id}
Update Project
Update a project.
```json
{
"tags": [
"Projects"
],
"summary": "Update Project",
"description": "Update a project.",
"operationId": "update_project_projects__team_id___project_id__patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"periodicity": {
"anyOf": [
{
"type": "string",
"enum": [
"MINUTE",
"HOUR",
"DAY",
"WEEK",
"MONTH",
"QUARTER",
"YEAR"
],
"title": "Periodicity",
"description": "Schema for periodicity."
},
{
"type": "null"
}
],
"description": "Periodicity for project, must be capital letter."
},
"currency_code": {
"anyOf": [
{
"type": "string",
"maxLength": 3,
"minLength": 3
},
{
"type": "null"
}
],
"title": "Currency Code",
"description": "Currency code for project, must be capital letter and follow ISO 4217, check `/info/currencies`.",
"one_of": [
"AED",
"AFN",
"ALL",
"AMD",
"ANG",
"AOA",
"ARS",
"AUD",
"AWG",
"AZN",
"BAM",
"BBD",
"BDT",
"BGN",
"BHD",
"BIF",
"BMD",
"BND",
"BOB",
"BRL",
"BSD",
"BTN",
"BWP",
"BYN",
"BZD",
"CAD",
"CDF",
"CHF",
"CLP",
"CNY",
"COP",
"CRC",
"CUC",
"CUP",
"CVE",
"CZK",
"DJF",
"DKK",
"DOP",
"DZD",
"EGP",
"ERN",
"ETB",
"EUR",
"FJD",
"FKP",
"GBP",
"GEL",
"GHS",
"GIP",
"GMD",
"GNF",
"GTQ",
"GYD",
"HKD",
"HNL",
"HRK",
"HTG",
"HUF",
"IDR",
"ILS",
"INR",
"IQD",
"IRR",
"ISK",
"JMD",
"JOD",
"JPY",
"KES",
"KGS",
"KHR",
"KMF",
"KPW",
"KRW",
"KWD",
"KYD",
"KZT",
"LAK",
"LBP",
"LKR",
"LRD",
"LSL",
"LYD",
"MAD",
"MDL",
"MGA",
"MKD",
"MMK",
"MNT",
"MOP",
"MRU",
"MUR",
"MVR",
"MWK",
"MXN",
"MYR",
"MZN",
"NAD",
"NGN",
"NIO",
"NOK",
"NPR",
"NZD",
"OMR",
"PAB",
"PEN",
"PGK",
"PHP",
"PKR",
"PLN",
"PYG",
"QAR",
"RON",
"RSD",
"RUB",
"RWF",
"SAR",
"SBD",
"SCR",
"SDG",
"SEK",
"SGD",
"SHP",
"SLL",
"SOS",
"SRD",
"SSP",
"STN",
"SVC",
"SYP",
"SZL",
"THB",
"TJS",
"TMT",
"TND",
"TOP",
"TRY",
"TTD",
"TWD",
"TZS",
"UAH",
"UGX",
"USD",
"UYU",
"UZS",
"VES",
"VND",
"VUV",
"WST",
"XAF",
"XCD",
"XOF",
"XPF",
"YER",
"ZAR",
"ZMW",
"ZWL"
]
},
"name": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
],
"title": "Name",
"description": "name attribute for project"
},
"slug": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Slug",
"description": "slug for project"
},
"activity_dashboard_mode": {
"anyOf": [
{
"type": "string",
"enum": [
"EFFECTS",
"ACTIVE"
],
"title": "ActivityDasboardMode",
"description": "Type of activity dasboard."
},
{
"type": "null"
}
],
"description": "Default activity dashborad model"
},
"settings": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Settings",
"description": "Custom UI settings"
}
},
"type": "object",
"title": "ProjectsUpdate",
"description": "Schema for partial project updates.",
"examples": [
{
"activity_dashboard_mode": "ACTIVE",
"currency_code": "EUR",
"name": "Q4 Marketing Analysis Updated",
"periodicity": "MONTH",
"settings": {
"theme": "dark",
"timezone": "UTC"
},
"slug": "q4-marketing-updated"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"slug": {
"type": "string",
"title": "Slug"
},
"periodicity": {
"type": "string",
"enum": [
"MINUTE",
"HOUR",
"DAY",
"WEEK",
"MONTH",
"QUARTER",
"YEAR"
],
"title": "Periodicity",
"description": "Schema for periodicity."
},
"currency_code": {
"type": "string",
"title": "Currency Code"
},
"created_date": {
"type": "string",
"format": "date-time",
"title": "Created Date"
},
"last_used_date": {
"type": "string",
"format": "date-time",
"title": "Last Used Date"
},
"variables_data_version": {
"type": "integer",
"title": "Variables Data Version",
"default": 0
},
"activity_dashboard_mode": {
"type": "string",
"enum": [
"EFFECTS",
"ACTIVE"
],
"title": "ActivityDasboardMode",
"description": "Type of activity dasboard."
},
"settings": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Settings"
},
"countries": {
"items": {
"type": "string"
},
"type": "array",
"title": "Countries"
},
"regions": {
"items": {
"type": "string"
},
"type": "array",
"title": "Regions"
},
"groupings": {
"items": {
"type": "string"
},
"type": "array",
"title": "Groupings"
},
"products": {
"items": {
"type": "string"
},
"type": "array",
"title": "Products"
},
"num_countries": {
"type": "integer",
"title": "Num Countries",
"default": 0
},
"num_regions": {
"type": "integer",
"title": "Num Regions",
"default": 0
},
"num_data_sources_uploaded": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Num Data Sources Uploaded"
},
"num_model_combinations_built": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Num Model Combinations Built"
},
"num_model_combinations": {
"type": "integer",
"title": "Num Model Combinations",
"default": 0
},
"active_models": {
"items": {
"properties": {
"country": {
"type": "string",
"title": "Country"
},
"region": {
"type": "string",
"title": "Region"
},
"grouping": {
"type": "string",
"title": "Grouping"
},
"targets": {
"type": "integer",
"title": "Targets"
},
"quality_score": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Quality Score"
}
},
"type": "object",
"required": [
"country",
"region",
"grouping",
"targets"
],
"title": "ActiveModelMetrics",
"description": "Per-active-model targets + quality score, one entry per Selected model."
},
"type": "array",
"title": "Active Models"
},
"active_dataset": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
{
"type": "null"
}
]
},
"latest_data_point_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Latest Data Point Date"
},
"latest_upload_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Latest Upload Date"
},
"latest_prediction_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Latest Prediction Date"
},
"total_media_spend": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Total Media Spend"
},
"total_sales": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Total Sales"
},
"avg_brand_value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Avg Brand Value"
},
"latest_effect_roi": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Latest Effect Roi"
}
},
"type": "object",
"required": [
"Id",
"name",
"slug",
"periodicity",
"currency_code",
"created_date",
"last_used_date",
"activity_dashboard_mode"
],
"title": "Projects",
"description": "Schema for project response.",
"examples": [
{
"Id": 1,
"active_models": [
{
"country": "US",
"grouping": "all",
"quality_score": 0.92,
"region": "West",
"targets": 3
}
],
"activity_dashboard_mode": "ACTIVE",
"countries": [
"US",
"UK"
],
"created_date": "2024-01-15T10:30:00",
"currency_code": "USD",
"last_used_date": "2024-12-01T14:22:00",
"latest_effect_roi": 1.45,
"name": "Q4 Marketing Analysis",
"num_countries": 2,
"num_data_sources_uploaded": 3,
"periodicity": "WEEK",
"products": [
"ProductA",
"ProductB"
],
"regions": [
"West",
"East"
],
"slug": "q4-marketing-2024"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Project (/api/projects/delete_project_projects__team_id___project_id__delete)
Delete a project.
## DELETE /api/projects/{team_id}/{project_id}
Delete Project
Delete a project.
```json
{
"tags": [
"Projects"
],
"summary": "Delete Project",
"description": "Delete a project.",
"operationId": "delete_project_projects__team_id___project_id__delete",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Project Active History (/api/projects/get_project_active_history_projects__team_id___project_id__active_history_get)
Return activation/deactivation events for this project, grouped by type.
Each history row represents one state transition:
- IId set -> the entity became Selected (activated)
- IId null -> the previously-selected entity was deselected or soft-deleted
Time-range semantics
--------------------
Suppose for datasets the project has had this activation timeline::
ds1 active 2024-01-01 -> 2025-01-01
ds2 active 2025-01-01 -> 2026-01-01
ds3 active 2026-01-01 -> (still active)
1. **Window with no transitions** -- one entity active the whole time.
`?start_date=2025-03-01&end_date=2025-06-01` returns the ds2 activation
at 2025-01-01 (carried in from before the window) so the caller can see
that ds2 was the active dataset throughout the window.
2. **Window covering a transition** -- multiple entities seen.
`?start_date=2024-12-01&end_date=2025-02-01` returns the ds1 activation
at 2024-01-01 (carried in), the ds1 deactivation at 2025-01-01, and the
ds2 activation at 2025-01-01 -- enough to reconstruct the full active
timeline across the window.
3. **Open-ended window** -- omit `start_date` to retrieve every event up to
`end_date`, or omit both to retrieve the full project history.
## GET /api/projects/{team_id}/{project_id}/active-history
Get Project Active History
Return activation/deactivation events for this project, grouped by type.
Each history row represents one state transition:
- IId set -> the entity became Selected (activated)
- IId null -> the previously-selected entity was deselected or soft-deleted
Time-range semantics
--------------------
Suppose for datasets the project has had this activation timeline::
ds1 active 2024-01-01 -> 2025-01-01
ds2 active 2025-01-01 -> 2026-01-01
ds3 active 2026-01-01 -> (still active)
1. **Window with no transitions** -- one entity active the whole time.
`?start_date=2025-03-01&end_date=2025-06-01` returns the ds2 activation
at 2025-01-01 (carried in from before the window) so the caller can see
that ds2 was the active dataset throughout the window.
2. **Window covering a transition** -- multiple entities seen.
`?start_date=2024-12-01&end_date=2025-02-01` returns the ds1 activation
at 2024-01-01 (carried in), the ds1 deactivation at 2025-01-01, and the
ds2 activation at 2025-01-01 -- enough to reconstruct the full active
timeline across the window.
3. **Open-ended window** -- omit `start_date` to retrieve every event up to
`end_date`, or omit both to retrieve the full project history.
```json
{
"tags": [
"Projects"
],
"summary": "Get Project Active History",
"description": "Return activation/deactivation events for this project, grouped by type.\n\nEach history row represents one state transition:\n- IId set -> the entity became Selected (activated)\n- IId null -> the previously-selected entity was deselected or soft-deleted\n\nTime-range semantics\n--------------------\nSuppose for datasets the project has had this activation timeline::\n\n ds1 active 2024-01-01 -> 2025-01-01\n ds2 active 2025-01-01 -> 2026-01-01\n ds3 active 2026-01-01 -> (still active)\n\n1. **Window with no transitions** -- one entity active the whole time.\n `?start_date=2025-03-01&end_date=2025-06-01` returns the ds2 activation\n at 2025-01-01 (carried in from before the window) so the caller can see\n that ds2 was the active dataset throughout the window.\n\n2. **Window covering a transition** -- multiple entities seen.\n `?start_date=2024-12-01&end_date=2025-02-01` returns the ds1 activation\n at 2024-01-01 (carried in), the ds1 deactivation at 2025-01-01, and the\n ds2 activation at 2025-01-01 -- enough to reconstruct the full active\n timeline across the window.\n\n3. **Open-ended window** -- omit `start_date` to retrieve every event up to\n `end_date`, or omit both to retrieve the full project history.",
"operationId": "get_project_active_history_projects__team_id___project_id__active_history_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"enum": [
"dataset",
"model",
"attribution_set"
],
"title": "ActiveHistoryType",
"description": "Entity types tracked in project active-history."
},
{
"type": "null"
}
],
"description": "Restrict to one entity type. Omit to return all three grouped.",
"title": "Type"
},
"description": "Restrict to one entity type. Omit to return all three grouped."
},
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Lower bound (ISO 8601) of the window. Events at or after this timestamp are returned. When set, the response also includes the single most-recent event strictly before start_date so callers can see what was active at the window boundary even if no transitions occurred inside the window.",
"title": "Start Date"
},
"description": "Lower bound (ISO 8601) of the window. Events at or after this timestamp are returned. When set, the response also includes the single most-recent event strictly before start_date so callers can see what was active at the window boundary even if no transitions occurred inside the window."
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "Upper bound (ISO 8601) of the window. Events at or before this timestamp are returned.",
"title": "End Date"
},
"description": "Upper bound (ISO 8601) of the window. Events at or before this timestamp are returned."
},
{
"name": "action",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"enum": [
"activated",
"deactivated"
],
"title": "ActiveHistoryAction",
"description": "Active-history event action."
},
{
"type": "null"
}
],
"description": "Filter to activation or deactivation events.",
"title": "Action"
},
"description": "Filter to activation or deactivation events."
},
{
"name": "updated_by_user",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Exact-match filter for UpdatedByUser.",
"title": "Updated By User"
},
"description": "Exact-match filter for UpdatedByUser."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 5000,
"minimum": 1,
"description": "Maximum rows per entity type (safety cap).",
"default": 500,
"title": "Limit"
},
"description": "Maximum rows per entity type (safety cap)."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"dataset": {
"anyOf": [
{
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"IId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Iid"
},
"Action": {
"type": "string",
"enum": [
"activated",
"deactivated"
],
"title": "ActiveHistoryAction",
"description": "Active-history event action."
},
"UpdatedByUser": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updatedbyuser"
},
"UpdatedAt": {
"type": "string",
"format": "date-time",
"title": "Updatedat"
}
},
"type": "object",
"required": [
"Id",
"IId",
"Action",
"UpdatedByUser",
"UpdatedAt"
],
"title": "ActiveHistoryEntry",
"description": "A dataset or attribution-set activation/deactivation event."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Dataset"
},
"model": {
"anyOf": [
{
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"IId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Iid"
},
"Action": {
"type": "string",
"enum": [
"activated",
"deactivated"
],
"title": "ActiveHistoryAction",
"description": "Active-history event action."
},
"UpdatedByUser": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updatedbyuser"
},
"UpdatedAt": {
"type": "string",
"format": "date-time",
"title": "Updatedat"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"Id",
"IId",
"Action",
"UpdatedByUser",
"UpdatedAt",
"Country",
"Region",
"Grouping"
],
"title": "ModelActiveHistoryEntry",
"description": "A model activation/deactivation event with modelling-combination context."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Model"
},
"attribution_set": {
"anyOf": [
{
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"IId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Iid"
},
"Action": {
"type": "string",
"enum": [
"activated",
"deactivated"
],
"title": "ActiveHistoryAction",
"description": "Active-history event action."
},
"UpdatedByUser": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updatedbyuser"
},
"UpdatedAt": {
"type": "string",
"format": "date-time",
"title": "Updatedat"
}
},
"type": "object",
"required": [
"Id",
"IId",
"Action",
"UpdatedByUser",
"UpdatedAt"
],
"title": "ActiveHistoryEntry",
"description": "A dataset or attribution-set activation/deactivation event."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attribution Set"
}
},
"type": "object",
"title": "ActiveHistoryResponse",
"description": "Grouped active-history events across entity types."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Project Resources (/api/projects/get_project_resources_projects__team_id___project_id__resources_get)
Get list of resources from a project.
## GET /api/projects/{team_id}/{project_id}/resources
Get Project Resources
Get list of resources from a project.
```json
{
"tags": [
"Projects"
],
"summary": "Get Project Resources",
"description": "Get list of resources from a project.",
"operationId": "get_project_resources_projects__team_id___project_id__resources_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"DataImports": {
"type": "integer",
"title": "Dataimports"
},
"DataSet": {
"type": "integer",
"title": "Dataset"
},
"Models": {
"type": "integer",
"title": "Models"
},
"SimulationJobs": {
"type": "integer",
"title": "Simulationjobs"
},
"PredictionJobs": {
"type": "integer",
"title": "Predictionjobs"
},
"Attribution": {
"type": "integer",
"title": "Attribution"
},
"AttributionSet": {
"type": "integer",
"title": "Attributionset"
},
"CompletedAttribution": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
},
{
"type": "null"
}
]
},
"ActiveDataSet": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
{
"type": "null"
}
]
},
"ActiveModel": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
},
{
"type": "null"
}
]
},
"ActiveAttributionSet": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Selected": {
"type": "boolean",
"title": "Selected"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"IId",
"Selected",
"CreatedDate",
"Status"
],
"title": "AttributionSetRef",
"description": "reference schema for Attribution set."
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"DataImports",
"DataSet",
"Models",
"SimulationJobs",
"PredictionJobs",
"Attribution",
"AttributionSet"
],
"title": "ProjectResources",
"description": "Schema for project resources."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Model Quality Rules (/api/projects/get_model_quality_rules_projects__team_id___project_id__model_quality_rules_get)
Return all model quality rules for a project (empty list if none stored).
## GET /api/projects/{team_id}/{project_id}/model-quality-rules
Get Model Quality Rules
Return all model quality rules for a project (empty list if none stored).
```json
{
"tags": [
"Projects"
],
"summary": "Get Model Quality Rules",
"description": "Return all model quality rules for a project (empty list if none stored).",
"operationId": "get_model_quality_rules_projects__team_id___project_id__model_quality_rules_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"rules": {
"items": {
"properties": {
"id": {
"type": "string",
"minLength": 1,
"title": "Id"
},
"metric": {
"oneOf": [
{
"properties": {
"scope": {
"type": "string",
"const": "fit",
"title": "Scope"
},
"kind": {
"type": "string",
"enum": [
"r2_score",
"bayes_r2",
"mean_absolute_error",
"mean_absolute_percentage_error",
"weighted_mean_absolute_percentage_error",
"mean_squared_error",
"root_mean_squared_error"
],
"title": "FitMetricKind",
"description": "Goodness-of-fit metric kinds (model performance)."
},
"stage": {
"type": "string",
"enum": [
"train",
"eval"
],
"title": "Stage",
"description": "Stage at which a fit metric is evaluated."
}
},
"type": "object",
"required": [
"scope",
"kind",
"stage"
],
"title": "FitMetric",
"description": "Fit-scope rule metric."
},
{
"properties": {
"scope": {
"type": "string",
"const": "sanity",
"title": "Scope"
},
"kind": {
"type": "string",
"enum": [
"share_of_effect",
"sum_effect",
"roi_effect",
"roi_revenue",
"roi_profit",
"cpx"
],
"title": "SanityMetricKind",
"description": "Sanity-check metric kinds (effect / ROI shape)."
},
"subject": {
"oneOf": [
{
"properties": {
"kind": {
"type": "string",
"const": "varGroup",
"title": "Kind"
},
"varGroup": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups",
"description": "Vraible groups."
},
"filters": {
"anyOf": [
{
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Filters"
}
},
"type": "object",
"required": [
"kind",
"varGroup"
],
"title": "SanityVarGroupSubject",
"description": "Sanity subject targeting a variable group."
},
{
"properties": {
"kind": {
"type": "string",
"const": "variable",
"title": "Kind"
},
"varSlug": {
"type": "string",
"title": "Varslug"
}
},
"type": "object",
"required": [
"kind",
"varSlug"
],
"title": "SanityVariableSubject",
"description": "Sanity subject targeting a single variable by slug."
}
],
"title": "Subject",
"discriminator": {
"propertyName": "kind",
"mapping": {
"varGroup": "#/components/schemas/SanityVarGroupSubject",
"variable": "#/components/schemas/SanityVariableSubject"
}
}
}
},
"type": "object",
"required": [
"scope",
"kind",
"subject"
],
"title": "SanityMetric",
"description": "Sanity-scope rule metric."
}
],
"title": "Metric",
"discriminator": {
"propertyName": "scope",
"mapping": {
"fit": "#/components/schemas/FitMetric",
"sanity": "#/components/schemas/SanityMetric"
}
}
},
"op": {
"type": "string",
"enum": [
"gte",
"lte"
],
"title": "RuleOp",
"description": "Comparison operator for a model quality rule threshold."
},
"threshold": {
"type": "number",
"title": "Threshold"
},
"enabled": {
"type": "boolean",
"title": "Enabled",
"default": true
},
"onMissing": {
"default": "ignore",
"type": "string",
"enum": [
"ignore",
"fail",
"warn"
],
"title": "RuleOnMissing",
"description": "Behaviour when a rule's target metric is missing from a model run."
},
"target": {
"oneOf": [
{
"properties": {
"kind": {
"type": "string",
"const": "global",
"title": "Kind"
}
},
"type": "object",
"required": [
"kind"
],
"title": "TargetGlobal",
"description": "Rule applies globally across all responses."
},
{
"properties": {
"kind": {
"type": "string",
"const": "kpiType",
"title": "Kind"
},
"varGroup": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups",
"description": "Vraible groups."
}
},
"type": "object",
"required": [
"kind",
"varGroup"
],
"title": "TargetKpiType",
"description": "Rule applies to responses with a given KPI variable group."
},
{
"properties": {
"kind": {
"type": "string",
"const": "response",
"title": "Kind"
},
"responseSlug": {
"type": "string",
"title": "Responseslug"
}
},
"type": "object",
"required": [
"kind",
"responseSlug"
],
"title": "TargetResponse",
"description": "Rule applies to a single response variable."
}
],
"title": "Target",
"discriminator": {
"propertyName": "kind",
"mapping": {
"global": "#/components/schemas/TargetGlobal",
"kpiType": "#/components/schemas/TargetKpiType",
"response": "#/components/schemas/TargetResponse"
}
}
}
},
"type": "object",
"required": [
"id",
"metric",
"op",
"threshold",
"target"
],
"title": "QualityRuleSchema",
"description": "A single model quality check rule."
},
"type": "array",
"title": "Rules"
}
},
"type": "object",
"required": [
"rules"
],
"title": "QualityRulesResponse",
"description": "Response body for GET/PUT /projects/{...}/model-quality-rules."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Put Model Quality Rules (/api/projects/put_model_quality_rules_projects__team_id___project_id__model_quality_rules_put)
Reconcile the project's rules against the incoming set.
Rules are matched by `RuleId`:
- new ids are inserted,
- existing ids whose columns or filters changed are updated in place,
- existing ids absent from the body are deleted (cascade removes filters),
- unchanged rows are left untouched so their `Id` is stable across calls.
## PUT /api/projects/{team_id}/{project_id}/model-quality-rules
Put Model Quality Rules
Reconcile the project's rules against the incoming set.
Rules are matched by `RuleId`:
- new ids are inserted,
- existing ids whose columns or filters changed are updated in place,
- existing ids absent from the body are deleted (cascade removes filters),
- unchanged rows are left untouched so their `Id` is stable across calls.
```json
{
"tags": [
"Projects"
],
"summary": "Put Model Quality Rules",
"description": "Reconcile the project's rules against the incoming set.\n\nRules are matched by `RuleId`:\n- new ids are inserted,\n- existing ids whose columns or filters changed are updated in place,\n- existing ids absent from the body are deleted (cascade removes filters),\n- unchanged rows are left untouched so their `Id` is stable across calls.",
"operationId": "put_model_quality_rules_projects__team_id___project_id__model_quality_rules_put",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"rules": {
"items": {
"properties": {
"id": {
"type": "string",
"minLength": 1,
"title": "Id"
},
"metric": {
"oneOf": [
{
"properties": {
"scope": {
"type": "string",
"const": "fit",
"title": "Scope"
},
"kind": {
"type": "string",
"enum": [
"r2_score",
"bayes_r2",
"mean_absolute_error",
"mean_absolute_percentage_error",
"weighted_mean_absolute_percentage_error",
"mean_squared_error",
"root_mean_squared_error"
],
"title": "FitMetricKind",
"description": "Goodness-of-fit metric kinds (model performance)."
},
"stage": {
"type": "string",
"enum": [
"train",
"eval"
],
"title": "Stage",
"description": "Stage at which a fit metric is evaluated."
}
},
"type": "object",
"required": [
"scope",
"kind",
"stage"
],
"title": "FitMetric",
"description": "Fit-scope rule metric."
},
{
"properties": {
"scope": {
"type": "string",
"const": "sanity",
"title": "Scope"
},
"kind": {
"type": "string",
"enum": [
"share_of_effect",
"sum_effect",
"roi_effect",
"roi_revenue",
"roi_profit",
"cpx"
],
"title": "SanityMetricKind",
"description": "Sanity-check metric kinds (effect / ROI shape)."
},
"subject": {
"oneOf": [
{
"properties": {
"kind": {
"type": "string",
"const": "varGroup",
"title": "Kind"
},
"varGroup": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups",
"description": "Vraible groups."
},
"filters": {
"anyOf": [
{
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Filters"
}
},
"type": "object",
"required": [
"kind",
"varGroup"
],
"title": "SanityVarGroupSubject",
"description": "Sanity subject targeting a variable group."
},
{
"properties": {
"kind": {
"type": "string",
"const": "variable",
"title": "Kind"
},
"varSlug": {
"type": "string",
"title": "Varslug"
}
},
"type": "object",
"required": [
"kind",
"varSlug"
],
"title": "SanityVariableSubject",
"description": "Sanity subject targeting a single variable by slug."
}
],
"title": "Subject",
"discriminator": {
"propertyName": "kind",
"mapping": {
"varGroup": "#/components/schemas/SanityVarGroupSubject",
"variable": "#/components/schemas/SanityVariableSubject"
}
}
}
},
"type": "object",
"required": [
"scope",
"kind",
"subject"
],
"title": "SanityMetric",
"description": "Sanity-scope rule metric."
}
],
"title": "Metric",
"discriminator": {
"propertyName": "scope",
"mapping": {
"fit": "#/components/schemas/FitMetric",
"sanity": "#/components/schemas/SanityMetric"
}
}
},
"op": {
"type": "string",
"enum": [
"gte",
"lte"
],
"title": "RuleOp",
"description": "Comparison operator for a model quality rule threshold."
},
"threshold": {
"type": "number",
"title": "Threshold"
},
"enabled": {
"type": "boolean",
"title": "Enabled",
"default": true
},
"onMissing": {
"default": "ignore",
"type": "string",
"enum": [
"ignore",
"fail",
"warn"
],
"title": "RuleOnMissing",
"description": "Behaviour when a rule's target metric is missing from a model run."
},
"target": {
"oneOf": [
{
"properties": {
"kind": {
"type": "string",
"const": "global",
"title": "Kind"
}
},
"type": "object",
"required": [
"kind"
],
"title": "TargetGlobal",
"description": "Rule applies globally across all responses."
},
{
"properties": {
"kind": {
"type": "string",
"const": "kpiType",
"title": "Kind"
},
"varGroup": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups",
"description": "Vraible groups."
}
},
"type": "object",
"required": [
"kind",
"varGroup"
],
"title": "TargetKpiType",
"description": "Rule applies to responses with a given KPI variable group."
},
{
"properties": {
"kind": {
"type": "string",
"const": "response",
"title": "Kind"
},
"responseSlug": {
"type": "string",
"title": "Responseslug"
}
},
"type": "object",
"required": [
"kind",
"responseSlug"
],
"title": "TargetResponse",
"description": "Rule applies to a single response variable."
}
],
"title": "Target",
"discriminator": {
"propertyName": "kind",
"mapping": {
"global": "#/components/schemas/TargetGlobal",
"kpiType": "#/components/schemas/TargetKpiType",
"response": "#/components/schemas/TargetResponse"
}
}
}
},
"type": "object",
"required": [
"id",
"metric",
"op",
"threshold",
"target"
],
"title": "QualityRuleSchema",
"description": "A single model quality check rule."
},
"type": "array",
"title": "Rules"
}
},
"type": "object",
"required": [
"rules"
],
"title": "QualityRulesRequest",
"description": "Request body for PUT /projects/{...}/model-quality-rules."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"rules": {
"items": {
"properties": {
"id": {
"type": "string",
"minLength": 1,
"title": "Id"
},
"metric": {
"oneOf": [
{
"properties": {
"scope": {
"type": "string",
"const": "fit",
"title": "Scope"
},
"kind": {
"type": "string",
"enum": [
"r2_score",
"bayes_r2",
"mean_absolute_error",
"mean_absolute_percentage_error",
"weighted_mean_absolute_percentage_error",
"mean_squared_error",
"root_mean_squared_error"
],
"title": "FitMetricKind",
"description": "Goodness-of-fit metric kinds (model performance)."
},
"stage": {
"type": "string",
"enum": [
"train",
"eval"
],
"title": "Stage",
"description": "Stage at which a fit metric is evaluated."
}
},
"type": "object",
"required": [
"scope",
"kind",
"stage"
],
"title": "FitMetric",
"description": "Fit-scope rule metric."
},
{
"properties": {
"scope": {
"type": "string",
"const": "sanity",
"title": "Scope"
},
"kind": {
"type": "string",
"enum": [
"share_of_effect",
"sum_effect",
"roi_effect",
"roi_revenue",
"roi_profit",
"cpx"
],
"title": "SanityMetricKind",
"description": "Sanity-check metric kinds (effect / ROI shape)."
},
"subject": {
"oneOf": [
{
"properties": {
"kind": {
"type": "string",
"const": "varGroup",
"title": "Kind"
},
"varGroup": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups",
"description": "Vraible groups."
},
"filters": {
"anyOf": [
{
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Filters"
}
},
"type": "object",
"required": [
"kind",
"varGroup"
],
"title": "SanityVarGroupSubject",
"description": "Sanity subject targeting a variable group."
},
{
"properties": {
"kind": {
"type": "string",
"const": "variable",
"title": "Kind"
},
"varSlug": {
"type": "string",
"title": "Varslug"
}
},
"type": "object",
"required": [
"kind",
"varSlug"
],
"title": "SanityVariableSubject",
"description": "Sanity subject targeting a single variable by slug."
}
],
"title": "Subject",
"discriminator": {
"propertyName": "kind",
"mapping": {
"varGroup": "#/components/schemas/SanityVarGroupSubject",
"variable": "#/components/schemas/SanityVariableSubject"
}
}
}
},
"type": "object",
"required": [
"scope",
"kind",
"subject"
],
"title": "SanityMetric",
"description": "Sanity-scope rule metric."
}
],
"title": "Metric",
"discriminator": {
"propertyName": "scope",
"mapping": {
"fit": "#/components/schemas/FitMetric",
"sanity": "#/components/schemas/SanityMetric"
}
}
},
"op": {
"type": "string",
"enum": [
"gte",
"lte"
],
"title": "RuleOp",
"description": "Comparison operator for a model quality rule threshold."
},
"threshold": {
"type": "number",
"title": "Threshold"
},
"enabled": {
"type": "boolean",
"title": "Enabled",
"default": true
},
"onMissing": {
"default": "ignore",
"type": "string",
"enum": [
"ignore",
"fail",
"warn"
],
"title": "RuleOnMissing",
"description": "Behaviour when a rule's target metric is missing from a model run."
},
"target": {
"oneOf": [
{
"properties": {
"kind": {
"type": "string",
"const": "global",
"title": "Kind"
}
},
"type": "object",
"required": [
"kind"
],
"title": "TargetGlobal",
"description": "Rule applies globally across all responses."
},
{
"properties": {
"kind": {
"type": "string",
"const": "kpiType",
"title": "Kind"
},
"varGroup": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups",
"description": "Vraible groups."
}
},
"type": "object",
"required": [
"kind",
"varGroup"
],
"title": "TargetKpiType",
"description": "Rule applies to responses with a given KPI variable group."
},
{
"properties": {
"kind": {
"type": "string",
"const": "response",
"title": "Kind"
},
"responseSlug": {
"type": "string",
"title": "Responseslug"
}
},
"type": "object",
"required": [
"kind",
"responseSlug"
],
"title": "TargetResponse",
"description": "Rule applies to a single response variable."
}
],
"title": "Target",
"discriminator": {
"propertyName": "kind",
"mapping": {
"global": "#/components/schemas/TargetGlobal",
"kpiType": "#/components/schemas/TargetKpiType",
"response": "#/components/schemas/TargetResponse"
}
}
}
},
"type": "object",
"required": [
"id",
"metric",
"op",
"threshold",
"target"
],
"title": "QualityRuleSchema",
"description": "A single model quality check rule."
},
"type": "array",
"title": "Rules"
}
},
"type": "object",
"required": [
"rules"
],
"title": "QualityRulesResponse",
"description": "Response body for GET/PUT /projects/{...}/model-quality-rules."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Datasets (/api/datasets/list_datasets_projects__team_id___project_id__datasets_get)
List datasets.
Retrieves a paginated list of datasets in a project, with optional
filters like names of simulation job where the dataset was used.
## GET /api/projects/{team_id}/{project_id}/datasets
List Datasets
List datasets.
Retrieves a paginated list of datasets in a project, with optional
filters like names of simulation job where the dataset was used.
```json
{
"tags": [
"Datasets"
],
"summary": "List Datasets",
"description": "List datasets.\n\nRetrieves a paginated list of datasets in a project, with optional\nfilters like names of simulation job where the dataset was used.",
"operationId": "list_datasets_projects__team_id___project_id__datasets_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"complete\"]]}'\n - Active dataset: filters='{\"Selected\": [[\"=\", \"true\"]]}'\n - By name: filters='{\"Name\": [[\"contains\", \"Marketing\"]]}'\n - Recent datasets: filters='{\"CreatedDate\": [[\">=\", \"2024-01-01\"]]}'\n - By model usage: filters='{\"Models.Name\": [[\"contains\", \"USA_Model\"]]}'\n - Sort by date: filters='{\"CreatedDate\": [[\"orderby\", \"desc\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"complete\"]]}'\n - Active dataset: filters='{\"Selected\": [[\"=\", \"true\"]]}'\n - By name: filters='{\"Name\": [[\"contains\", \"Marketing\"]]}'\n - Recent datasets: filters='{\"CreatedDate\": [[\">=\", \"2024-01-01\"]]}'\n - By model usage: filters='{\"Models.Name\": [[\"contains\", \"USA_Model\"]]}'\n - Sort by date: filters='{\"CreatedDate\": [[\"orderby\", \"desc\"]]}'\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /datasets/{IId})"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active dataset for modeling"
},
"Name": {
"type": "string",
"title": "Name",
"description": "Dataset display name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Dataset creation timestamp"
},
"DataImports": {
"items": {
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"IId": {
"type": "integer",
"title": "Iid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"DatasetName": {
"type": "string",
"title": "Datasetname"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"External": {
"type": "boolean",
"title": "External"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"ModellingCombinations": {
"anyOf": [
{
"items": {
"properties": {
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"Country",
"Region",
"Grouping"
],
"title": "ModellingCombinationForDataImport",
"description": "Schema for modelling combination for data import."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Modellingcombinations"
}
},
"type": "object",
"required": [
"IId",
"Date",
"DatasetName",
"Status",
"External"
],
"title": "DataImportRef",
"description": "Reference schema for data import."
},
"type": "array",
"title": "Dataimports",
"description": "List of data imports included in this dataset"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Processing state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"Blocked": {
"type": "boolean",
"title": "Blocked",
"description": "True when at least one data value falls outside this dataset's variable limits. Blocked datasets are rejected by sim/pred/attribution/optimize/response-curve submission until the limits are patched to cover the data.",
"default": false
}
},
"type": "object",
"required": [
"IId",
"Selected",
"Name",
"CreatedDate",
"DataImports",
"Status"
],
"title": "DataSet",
"description": "Response schema for datasets (collections of data imports).",
"examples": [
{
"CreatedDate": "2024-01-15T10:30:00Z",
"CreatorId": "user-123",
"DataImports": [
{
"DatasetName": "Sales",
"Date": "2024-01-15T10:30:00",
"External": false,
"IId": 1,
"Status": "complete"
}
],
"IId": 1,
"Name": "Marketing Dataset Q4",
"Note": "Combined sales and marketing data",
"Selected": true,
"Status": "complete"
}
]
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[DataSet]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Create Dataset (/api/datasets/create_dataset_projects__team_id___project_id__datasets_post)
Create a new dataset.
This endpoint allows the creation of a new dataset within a specified project.
It can handle both existing datasets and new data imports.
## POST /api/projects/{team_id}/{project_id}/datasets
Create Dataset
Create a new dataset.
This endpoint allows the creation of a new dataset within a specified project.
It can handle both existing datasets and new data imports.
```json
{
"tags": [
"Datasets"
],
"summary": "Create Dataset",
"description": "Create a new dataset.\n\nThis endpoint allows the creation of a new dataset within a specified project.\nIt can handle both existing datasets and new data imports.",
"operationId": "create_dataset_projects__team_id___project_id__datasets_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"description": "Left empty to use all data upload available",
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Description for the model/dataset"
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"activate": {
"type": "boolean",
"title": "Activate",
"description": "Activate the model/dataset as soon as it is done training.",
"default": false
},
"upload_ids": {
"anyOf": [
{
"items": {
"anyOf": [
{
"type": "integer"
},
{
"properties": {
"upload_id": {
"type": "integer",
"title": "Upload Id",
"description": "The id of the upload to filter the data import by."
},
"variable_filters": {
"anyOf": [
{
"items": {
"properties": {
"country": {
"type": "string",
"title": "Country",
"description": "Country code to use for the modelling combination."
},
"region": {
"type": "string",
"title": "Region",
"description": "Region code to use for the modelling combination."
},
"grouping": {
"type": "string",
"title": "Grouping",
"description": "Grouping code to use for the modelling combination."
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Start Date",
"description": "The first date in the date range used to select data from the dataset"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "End Date",
"description": "The last date in the date range used to select data from the dataset."
},
"variable_id": {
"type": "integer",
"title": "Variable Id",
"description": "The id of the variable to filter the data import by."
}
},
"type": "object",
"required": [
"country",
"region",
"grouping",
"variable_id"
],
"title": "VariableFilter",
"description": "Schema for variable filter."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variable Filters",
"description": "List of variable filters to apply to the data import, will be merged with the provided `upload_id`."
}
},
"type": "object",
"required": [
"upload_id"
],
"title": "UploadFilter",
"description": "Schema for dataimport filter."
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Upload Ids",
"description": "List of data uploads to include in the new dataset, will be merged with the provided `dataset_ids`."
},
"dataset_ids": {
"anyOf": [
{
"items": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"properties": {
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
},
"variable_filters": {
"items": {
"properties": {
"country": {
"type": "string",
"title": "Country",
"description": "Country code to use for the modelling combination."
},
"region": {
"type": "string",
"title": "Region",
"description": "Region code to use for the modelling combination."
},
"grouping": {
"type": "string",
"title": "Grouping",
"description": "Grouping code to use for the modelling combination."
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Start Date",
"description": "The first date in the date range used to select data from the dataset"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "End Date",
"description": "The last date in the date range used to select data from the dataset."
},
"variable_id": {
"type": "integer",
"title": "Variable Id",
"description": "The id of the variable to filter the data import by."
}
},
"type": "object",
"required": [
"country",
"region",
"grouping",
"variable_id"
],
"title": "VariableFilter",
"description": "Schema for variable filter."
},
"type": "array",
"title": "Variable Filters",
"description": "List of selected variables that will be merged into the dataset. "
}
},
"type": "object",
"required": [
"dataset_id",
"variable_filters"
],
"title": "DatasetFilter",
"description": "Schema for dataset filter."
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Dataset Ids",
"description": "List of datasets to include in the new dataset where the data uploads they are comprised of will be merged with the provided upload_ids to form a new data set. Use the string active as a value if the to use the active dataset."
},
"external_datasets": {
"anyOf": [
{
"items": {
"properties": {
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Description for the model/dataset"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"indicators": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Indicators",
"description": "List of indicators"
},
"dataset_name": {
"type": "string",
"enum": [
"Macro",
"Weather"
],
"title": "Dataset Name"
}
},
"type": "object",
"required": [
"dataset_name"
],
"title": "DataUploadsExternalPost",
"description": "Schema for creating external datasource.",
"examples": [
{
"Name": "Macro Economic Indicators",
"Note": "External macro data for Q4",
"dataset_name": "Macro",
"indicators": [
"Short-term interest rates",
"Long-term interest rates",
"Consumer Confidence Index"
]
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "External Datasets",
"description": "External dataset to merge with dataset."
},
"variable_limits": {
"anyOf": [
{
"items": {
"properties": {
"VariableIId": {
"type": "integer",
"title": "Variableiid"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"MinLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Minlimit"
},
"MaxLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Maxlimit"
}
},
"type": "object",
"required": [
"VariableIId",
"Country",
"Region",
"Grouping"
],
"title": "PatchDatasetVariableLimit",
"description": "One row of a dataset-level variable-limits PATCH.\n\nTargets a single ``(VariableIId, Country, Region, Grouping)`` in\n``VariableStats``. ``MinLimit`` / ``MaxLimit`` are each independently\noptional: missing means \"do not change\"; an explicit ``null`` clears.",
"examples": [
{
"Country": "SWE",
"Grouping": "all",
"MaxLimit": 100000,
"MinLimit": 0,
"Region": "all",
"VariableIId": 1
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variable Limits",
"description": "Optional per-row VariableStats limits applied at dataset creation. Each row targets a single (VariableIId, Country, Region, Grouping) tuple that must exist in the new dataset; unknown tuples produce a 400. User-supplied values take precedence over both the source-dataset min/max merge and the data-derived defaults."
}
},
"type": "object",
"title": "DataSetRequest",
"examples": [
{
"activate": true,
"dataset_ids": [
"active",
5
],
"external_datasets": [
{
"Name": "Macro Indicators",
"Note": "Economic indicators",
"dataset_name": "Macro",
"indicators": [
"Short-term interest rates",
"Consumer Confidence Index"
]
}
],
"name": "Marketing Dataset Q4",
"note": "Combined sales and marketing data for Q4 analysis",
"upload_ids": [
1,
2,
{
"upload_id": 3,
"variable_filters": [
{
"country": "USA",
"end_date": "2024-12-31T00:00:00",
"grouping": "all",
"region": "all",
"start_date": "2024-01-01T00:00:00",
"variable_id": 101
}
]
}
],
"variable_limits": [
{
"Country": "USA",
"Grouping": "all",
"MaxLimit": 100000,
"MinLimit": 0,
"Region": "all",
"VariableIId": 101
}
]
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /datasets/{IId})"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active dataset for modeling"
},
"Name": {
"type": "string",
"title": "Name",
"description": "Dataset display name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Dataset creation timestamp"
},
"DataImports": {
"items": {
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"IId": {
"type": "integer",
"title": "Iid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"DatasetName": {
"type": "string",
"title": "Datasetname"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"External": {
"type": "boolean",
"title": "External"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"ModellingCombinations": {
"anyOf": [
{
"items": {
"properties": {
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"Country",
"Region",
"Grouping"
],
"title": "ModellingCombinationForDataImport",
"description": "Schema for modelling combination for data import."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Modellingcombinations"
}
},
"type": "object",
"required": [
"IId",
"Date",
"DatasetName",
"Status",
"External"
],
"title": "DataImportRef",
"description": "Reference schema for data import."
},
"type": "array",
"title": "Dataimports",
"description": "List of data imports included in this dataset"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Processing state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"Blocked": {
"type": "boolean",
"title": "Blocked",
"description": "True when at least one data value falls outside this dataset's variable limits. Blocked datasets are rejected by sim/pred/attribution/optimize/response-curve submission until the limits are patched to cover the data.",
"default": false
}
},
"type": "object",
"required": [
"IId",
"Selected",
"Name",
"CreatedDate",
"DataImports",
"Status"
],
"title": "DataSet",
"description": "Response schema for datasets (collections of data imports).",
"examples": [
{
"CreatedDate": "2024-01-15T10:30:00Z",
"CreatorId": "user-123",
"DataImports": [
{
"DatasetName": "Sales",
"Date": "2024-01-15T10:30:00",
"External": false,
"IId": 1,
"Status": "complete"
}
],
"IId": 1,
"Name": "Marketing Dataset Q4",
"Note": "Combined sales and marketing data",
"Selected": true,
"Status": "complete"
}
]
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Bulk Delete Datasets (/api/datasets/bulk_delete_datasets_projects__team_id___project_id__datasets_delete)
Bulk delete datasets matching the given filters.
Marks all matching datasets for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
Active datasets and those used in active models or attribution sets are excluded.
## DELETE /api/projects/{team_id}/{project_id}/datasets
Bulk Delete Datasets
Bulk delete datasets matching the given filters.
Marks all matching datasets for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
Active datasets and those used in active models or attribution sets are excluded.
```json
{
"tags": [
"Datasets"
],
"summary": "Bulk Delete Datasets",
"description": "Bulk delete datasets matching the given filters.\n\nMarks all matching datasets for deletion and publishes delete messages to\nRabbitMQ concurrently in the background via a single DB round-trip each.\nActive datasets and those used in active models or attribution sets are excluded.",
"operationId": "bulk_delete_datasets_projects__team_id___project_id__datasets_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /datasets.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"complete\"]]}'\n - By name: filters='{\"Name\": [[\"contains\", \"Marketing\"]]}'\n - By date: filters='{\"CreatedDate\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /datasets.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"complete\"]]}'\n - By name: filters='{\"Name\": [[\"contains\", \"Marketing\"]]}'\n - By date: filters='{\"CreatedDate\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n "
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Dataset Active History (/api/datasets/list_dataset_active_history_projects__team_id___project_id__datasets_active_history_get)
List the history of active dataset changes for this project.
## GET /api/projects/{team_id}/{project_id}/datasets/active-history
List Dataset Active History
List the history of active dataset changes for this project.
```json
{
"tags": [
"Datasets"
],
"summary": "List Dataset Active History",
"description": "List the history of active dataset changes for this project.",
"operationId": "list_dataset_active_history_projects__team_id___project_id__datasets_active_history_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "JSON filter expressions. Filterable fields: UpdatedAt (>=, <=), UpdatedByUser (=, contains), DataSetId (=, in). Example: filters='{\"UpdatedByUser\": [[\"=\", \"alice\"]]}'",
"title": "Filters"
},
"description": "JSON filter expressions. Filterable fields: UpdatedAt (>=, <=), UpdatedByUser (=, contains), DataSetId (=, in). Example: filters='{\"UpdatedByUser\": [[\"=\", \"alice\"]]}'"
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"DataSetId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Datasetid"
},
"UpdatedByUser": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updatedbyuser"
},
"UpdatedAt": {
"type": "string",
"format": "date-time",
"title": "Updatedat"
}
},
"type": "object",
"required": [
"Id",
"DataSetId",
"UpdatedByUser",
"UpdatedAt"
],
"title": "DataSetActiveHistory",
"description": "Response schema for dataset active history records."
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[DataSetActiveHistory]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Activate Dataset (/api/datasets/activate_dataset_projects__team_id___project_id__datasets__dataset_id__activate_post)
Activate a dataset.
This endpoint sets a specified dataset as active within a given project.
## POST /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/activate
Activate Dataset
Activate a dataset.
This endpoint sets a specified dataset as active within a given project.
```json
{
"tags": [
"Datasets"
],
"summary": "Activate Dataset",
"description": "Activate a dataset.\n\nThis endpoint sets a specified dataset as active within a given project.",
"operationId": "activate_dataset_projects__team_id___project_id__datasets__dataset_id__activate_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Deactivate Dataset (/api/datasets/deactivate_dataset_projects__team_id___project_id__datasets__dataset_id__activate_delete)
Deactivate the active dataset.
Clears the active state of the specified dataset. After this call the
project will have no active dataset until a new one is activated.
Path Parameters:
- dataset_id: The IId of the dataset to deactivate
Errors:
- 400 if the dataset is not currently active
## DELETE /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/activate
Deactivate Dataset
Deactivate the active dataset.
Clears the active state of the specified dataset. After this call the
project will have no active dataset until a new one is activated.
Path Parameters:
- dataset_id: The IId of the dataset to deactivate
Errors:
- 400 if the dataset is not currently active
```json
{
"tags": [
"Datasets"
],
"summary": "Deactivate Dataset",
"description": "Deactivate the active dataset.\n\nClears the active state of the specified dataset. After this call the\nproject will have no active dataset until a new one is activated.\n\nPath Parameters:\n - dataset_id: The IId of the dataset to deactivate\n\nErrors:\n - 400 if the dataset is not currently active",
"operationId": "deactivate_dataset_projects__team_id___project_id__datasets__dataset_id__activate_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Dataset (/api/datasets/get_dataset_projects__team_id___project_id__datasets__dataset_id__get)
Get details of a dataset.
Retrieves detailed information about a specific dataset in a project,
including related data imports.
## GET /api/projects/{team_id}/{project_id}/datasets/{dataset_id}
Get Dataset
Get details of a dataset.
Retrieves detailed information about a specific dataset in a project,
including related data imports.
```json
{
"tags": [
"Datasets"
],
"summary": "Get Dataset",
"description": "Get details of a dataset.\n\nRetrieves detailed information about a specific dataset in a project,\nincluding related data imports.",
"operationId": "get_dataset_projects__team_id___project_id__datasets__dataset_id__get",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"Task": {
"anyOf": [
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"Topic": {
"type": "string",
"enum": [
"ATTRIBUTIONSET",
"ATTRIBUTIONJOB",
"SIMULATIONJOB",
"PREDICTIONJOB",
"TRAINJOB",
"DATASET",
"DATAUPLOAD",
"GRAPHCONSTRUCT",
"GENERAL",
"OPTIMIZATIONJOB",
"RESPOSNSECURVEJOB",
"PRIORPOSTERIORJOB",
"EXCELJOB",
"GRAPHBASIC",
"FEATUREIMPORTANCE",
"GRAPHSYNERGY"
],
"title": "TaskTopics",
"description": "Task topics."
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"Id",
"Config",
"Topic",
"Status"
],
"title": "Task",
"description": "Reference task."
},
{
"type": "null"
}
]
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /datasets/{IId})"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active dataset for modeling"
},
"Name": {
"type": "string",
"title": "Name",
"description": "Dataset display name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Dataset creation timestamp"
},
"DataImports": {
"items": {
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"IId": {
"type": "integer",
"title": "Iid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"DatasetName": {
"type": "string",
"title": "Datasetname"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"External": {
"type": "boolean",
"title": "External"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"ModellingCombinations": {
"anyOf": [
{
"items": {
"properties": {
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"Country",
"Region",
"Grouping"
],
"title": "ModellingCombinationForDataImport",
"description": "Schema for modelling combination for data import."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Modellingcombinations"
}
},
"type": "object",
"required": [
"IId",
"Date",
"DatasetName",
"Status",
"External"
],
"title": "DataImportRef",
"description": "Reference schema for data import."
},
"type": "array",
"title": "Dataimports",
"description": "List of data imports included in this dataset"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Processing state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"Blocked": {
"type": "boolean",
"title": "Blocked",
"description": "True when at least one data value falls outside this dataset's variable limits. Blocked datasets are rejected by sim/pred/attribution/optimize/response-curve submission until the limits are patched to cover the data.",
"default": false
},
"Models": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
},
"type": "array",
"title": "Models",
"description": "Models trained on this dataset"
},
"Attributions": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
},
"type": "array",
"title": "Attributions",
"description": "Attribution jobs using this dataset"
},
"PredictionJobs": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status"
],
"title": "PredictionJobsRef",
"description": "Reference schema for prediction job."
},
"type": "array",
"title": "Predictionjobs",
"description": "Prediction jobs using this dataset"
},
"SimulationJobs": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"IsFromOptimization": {
"type": "boolean",
"title": "Isfromoptimization",
"description": "Whether this simulation was submitted by an optimization job.",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"IsFromOptimization"
],
"title": "SimulationJobsRef",
"description": "Reference schema for simulation Job."
},
"type": "array",
"title": "Simulationjobs",
"description": "Simulation jobs using this dataset"
},
"AttributionSets": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Selected": {
"type": "boolean",
"title": "Selected"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"IId",
"Selected",
"CreatedDate",
"Status"
],
"title": "AttributionSetRef",
"description": "reference schema for Attribution set."
},
"type": "array",
"title": "Attributionsets",
"description": "Attribution sets using this dataset"
}
},
"type": "object",
"required": [
"IId",
"Selected",
"Name",
"CreatedDate",
"DataImports",
"Status",
"Models",
"Attributions",
"PredictionJobs",
"SimulationJobs",
"AttributionSets"
],
"title": "DetailedDataSet",
"description": "Detailed response schema for datasets with related jobs and models.",
"examples": [
{
"CreatedDate": "2024-01-15T10:30:00Z",
"CreatorId": "user-123",
"DataImports": [
{
"DatasetName": "Sales",
"Date": "2024-01-15T10:30:00",
"External": false,
"IId": 1,
"Status": "complete"
}
],
"IId": 1,
"Name": "Marketing Dataset Q4",
"Note": "Combined sales and marketing data",
"Selected": true,
"Status": "complete",
"UIFilterAttributionSets": [],
"UIFilterAttributions": [],
"UIFilterModels": [],
"UIFilterPredictionJobs": [],
"UIFilterSimulationJobs": []
}
]
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Dataset (/api/datasets/update_dataset_projects__team_id___project_id__datasets__dataset_id__patch)
Update dataset attributes.
Modifies attributes like name or note for a specific dataset in a
project.
## PATCH /api/projects/{team_id}/{project_id}/datasets/{dataset_id}
Update Dataset
Update dataset attributes.
Modifies attributes like name or note for a specific dataset in a
project.
```json
{
"tags": [
"Datasets"
],
"summary": "Update Dataset",
"description": "Update dataset attributes.\n\nModifies attributes like name or note for a specific dataset in a\nproject.",
"operationId": "update_dataset_projects__team_id___project_id__datasets__dataset_id__patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Description for the model/dataset"
}
},
"type": "object",
"title": "PatchDataSet",
"description": "Schema for updating dataset attribute.",
"examples": [
{
"Name": "Updated Dataset Name",
"Note": "Updated description for the dataset"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /datasets/{IId})"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active dataset for modeling"
},
"Name": {
"type": "string",
"title": "Name",
"description": "Dataset display name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Dataset creation timestamp"
},
"DataImports": {
"items": {
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"IId": {
"type": "integer",
"title": "Iid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"DatasetName": {
"type": "string",
"title": "Datasetname"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"External": {
"type": "boolean",
"title": "External"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"ModellingCombinations": {
"anyOf": [
{
"items": {
"properties": {
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"Country",
"Region",
"Grouping"
],
"title": "ModellingCombinationForDataImport",
"description": "Schema for modelling combination for data import."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Modellingcombinations"
}
},
"type": "object",
"required": [
"IId",
"Date",
"DatasetName",
"Status",
"External"
],
"title": "DataImportRef",
"description": "Reference schema for data import."
},
"type": "array",
"title": "Dataimports",
"description": "List of data imports included in this dataset"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Processing state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"Blocked": {
"type": "boolean",
"title": "Blocked",
"description": "True when at least one data value falls outside this dataset's variable limits. Blocked datasets are rejected by sim/pred/attribution/optimize/response-curve submission until the limits are patched to cover the data.",
"default": false
}
},
"type": "object",
"required": [
"IId",
"Selected",
"Name",
"CreatedDate",
"DataImports",
"Status"
],
"title": "DataSet",
"description": "Response schema for datasets (collections of data imports).",
"examples": [
{
"CreatedDate": "2024-01-15T10:30:00Z",
"CreatorId": "user-123",
"DataImports": [
{
"DatasetName": "Sales",
"Date": "2024-01-15T10:30:00",
"External": false,
"IId": 1,
"Status": "complete"
}
],
"IId": 1,
"Name": "Marketing Dataset Q4",
"Note": "Combined sales and marketing data",
"Selected": true,
"Status": "complete"
}
]
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Dataset (/api/datasets/delete_dataset_projects__team_id___project_id__datasets__dataset_id__delete)
Delete a dataset.
Removes a dataset and its related jobs and attribution sets from a
project.
## DELETE /api/projects/{team_id}/{project_id}/datasets/{dataset_id}
Delete Dataset
Delete a dataset.
Removes a dataset and its related jobs and attribution sets from a
project.
```json
{
"tags": [
"Datasets"
],
"summary": "Delete Dataset",
"description": "Delete a dataset.\n\nRemoves a dataset and its related jobs and attribution sets from a\nproject.",
"operationId": "delete_dataset_projects__team_id___project_id__datasets__dataset_id__delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Dataset Variable Limits (/api/datasets/list_dataset_variable_limits_projects__team_id___project_id__datasets__dataset_id__variable_limits_get)
List per-variable, per-modelling-combination limits for a dataset.
Returns one row per ``(VariableIId, Country, Region, Grouping)`` present in
the dataset's ``VariableStats``. Limits unset on a given row come back as
``null``; the project-level ``Variables.MinLimit`` / ``MaxLimit`` envelope
is exposed separately via ``GET /project/{id}/variables``.
## GET /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/variable_limits
List Dataset Variable Limits
List per-variable, per-modelling-combination limits for a dataset.
Returns one row per ``(VariableIId, Country, Region, Grouping)`` present in
the dataset's ``VariableStats``. Limits unset on a given row come back as
``null``; the project-level ``Variables.MinLimit`` / ``MaxLimit`` envelope
is exposed separately via ``GET /project/{id}/variables``.
```json
{
"tags": [
"Datasets"
],
"summary": "List Dataset Variable Limits",
"description": "List per-variable, per-modelling-combination limits for a dataset.\n\nReturns one row per ``(VariableIId, Country, Region, Grouping)`` present in\nthe dataset's ``VariableStats``. Limits unset on a given row come back as\n``null``; the project-level ``Variables.MinLimit`` / ``MaxLimit`` envelope\nis exposed separately via ``GET /project/{id}/variables``.",
"operationId": "list_dataset_variable_limits_projects__team_id___project_id__datasets__dataset_id__variable_limits_get",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"VariableIId": {
"type": "integer",
"title": "Variableiid",
"description": "Variable IId within the project"
},
"Slug": {
"type": "string",
"title": "Slug",
"description": "Variable slug"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"MinLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Minlimit"
},
"MaxLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Maxlimit"
}
},
"type": "object",
"required": [
"VariableIId",
"Slug",
"Country",
"Region",
"Grouping"
],
"title": "DatasetVariableLimit",
"description": "Per-variable, per-modelling-combination dataset-level limits."
},
"title": "Response List Dataset Variable Limits Projects Team Id Project Id Datasets Dataset Id Variable Limits Get"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Patch Dataset Variable Limits (/api/datasets/patch_dataset_variable_limits_projects__team_id___project_id__datasets__dataset_id__variable_limits_patch)
Bulk-update dataset-level variable limits.
Rejected as a whole if any row would:
- Target a ``(VariableIId, Country, Region, Grouping)`` that doesn't exist
in this dataset's ``VariableStats`` (404 for the row).
- Violate the project envelope on ``Variables.MinLimit`` / ``MaxLimit``.
- Result in ``MinLimit >= MaxLimit``.
Forbidden once the dataset has been consumed by sim/pred/attribution/
optimize/response-curve/prior-posterior/Model — the way to get new limits
is to create a new dataset.
On success, ``DataSet.Blocked`` is re-computed against the dataset's data.
## PATCH /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/variable_limits
Patch Dataset Variable Limits
Bulk-update dataset-level variable limits.
Rejected as a whole if any row would:
- Target a ``(VariableIId, Country, Region, Grouping)`` that doesn't exist
in this dataset's ``VariableStats`` (404 for the row).
- Violate the project envelope on ``Variables.MinLimit`` / ``MaxLimit``.
- Result in ``MinLimit >= MaxLimit``.
Forbidden once the dataset has been consumed by sim/pred/attribution/
optimize/response-curve/prior-posterior/Model — the way to get new limits
is to create a new dataset.
On success, ``DataSet.Blocked`` is re-computed against the dataset's data.
```json
{
"tags": [
"Datasets"
],
"summary": "Patch Dataset Variable Limits",
"description": "Bulk-update dataset-level variable limits.\n\nRejected as a whole if any row would:\n- Target a ``(VariableIId, Country, Region, Grouping)`` that doesn't exist\n in this dataset's ``VariableStats`` (404 for the row).\n- Violate the project envelope on ``Variables.MinLimit`` / ``MaxLimit``.\n- Result in ``MinLimit >= MaxLimit``.\n\nForbidden once the dataset has been consumed by sim/pred/attribution/\noptimize/response-curve/prior-posterior/Model — the way to get new limits\nis to create a new dataset.\n\nOn success, ``DataSet.Blocked`` is re-computed against the dataset's data.",
"operationId": "patch_dataset_variable_limits_projects__team_id___project_id__datasets__dataset_id__variable_limits_patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"limits": {
"items": {
"properties": {
"VariableIId": {
"type": "integer",
"title": "Variableiid"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"MinLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Minlimit"
},
"MaxLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Maxlimit"
}
},
"type": "object",
"required": [
"VariableIId",
"Country",
"Region",
"Grouping"
],
"title": "PatchDatasetVariableLimit",
"description": "One row of a dataset-level variable-limits PATCH.\n\nTargets a single ``(VariableIId, Country, Region, Grouping)`` in\n``VariableStats``. ``MinLimit`` / ``MaxLimit`` are each independently\noptional: missing means \"do not change\"; an explicit ``null`` clears.",
"examples": [
{
"Country": "SWE",
"Grouping": "all",
"MaxLimit": 100000,
"MinLimit": 0,
"Region": "all",
"VariableIId": 1
}
]
},
"type": "array",
"minItems": 1,
"title": "Limits"
}
},
"type": "object",
"required": [
"limits"
],
"title": "PatchDatasetVariableLimits",
"description": "Bulk PATCH body for ``/datasets/{id}/variable_limits``.\n\nAll rows are validated up-front; the update is rejected as a whole on the\nfirst error so partial writes never happen."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"VariableIId": {
"type": "integer",
"title": "Variableiid",
"description": "Variable IId within the project"
},
"Slug": {
"type": "string",
"title": "Slug",
"description": "Variable slug"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"MinLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Minlimit"
},
"MaxLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Maxlimit"
}
},
"type": "object",
"required": [
"VariableIId",
"Slug",
"Country",
"Region",
"Grouping"
],
"title": "DatasetVariableLimit",
"description": "Per-variable, per-modelling-combination dataset-level limits."
},
"title": "Response Patch Dataset Variable Limits Projects Team Id Project Id Datasets Dataset Id Variable Limits Patch"
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Dataset (/api/datasets/download_dataset_projects__team_id___project_id__datasets__dataset_id__data_get)
Download dataset data.
Retrieves data from a specific dataset in a project as a CSV file,
merging data if no dataset name is specified.
## GET /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/data
Download Dataset
Download dataset data.
Retrieves data from a specific dataset in a project as a CSV file,
merging data if no dataset name is specified.
```json
{
"tags": [
"Datasets"
],
"summary": "Download Dataset",
"description": "Download dataset data.\n\nRetrieves data from a specific dataset in a project as a CSV file,\nmerging data if no dataset name is specified.",
"operationId": "download_dataset_projects__team_id___project_id__datasets__dataset_id__data_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "dataset_name",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra"
],
"title": "Dataset",
"description": "User upload datasets."
},
{
"type": "null"
}
],
"title": "Dataset Name"
}
},
{
"name": "output_format",
"in": "query",
"required": false,
"schema": {
"enum": [
"csv",
"parquet"
],
"type": "string",
"default": "csv",
"title": "Output Format"
}
},
{
"name": "country_code",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Three letters of country code",
"title": "Country Code"
},
"description": "Three letters of country code"
},
{
"name": "region_code",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Region code",
"title": "Region Code"
},
"description": "Region code"
},
{
"name": "grouping",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Grouping",
"title": "Grouping"
},
"description": "Grouping"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Variable (/api/datasets/download_variable_projects__team_id___project_id__datasets__dataset_id__variable_data_get)
Download dataset variable data.
Retrieves variable-specific data from a dataset in a project as CSV,
with optional filters like country.
## GET /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/variable_data
Download Variable
Download dataset variable data.
Retrieves variable-specific data from a dataset in a project as CSV,
with optional filters like country.
```json
{
"tags": [
"Datasets"
],
"summary": "Download Variable",
"description": "Download dataset variable data.\n\nRetrieves variable-specific data from a dataset in a project as CSV,\nwith optional filters like country.",
"operationId": "download_variable_projects__team_id___project_id__datasets__dataset_id__variable_data_get",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "data_filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n Filter data rows by geographic or other attributes.\n\n Examples:\n - By country: data_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - Multiple: data_filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By region: data_filters='{\"Region\": [[\"=\", \"northeast\"]]}'\n - By date: data_filters='{\"Date\": [[\">=\", \"2024-01-01\"]]}'\n ",
"title": "Data Filters"
},
"description": "\n Filter data rows by geographic or other attributes.\n\n Examples:\n - By country: data_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - Multiple: data_filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By region: data_filters='{\"Region\": [[\"=\", \"northeast\"]]}'\n - By date: data_filters='{\"Date\": [[\">=\", \"2024-01-01\"]]}'\n "
},
{
"name": "dataset_names",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra"
],
"title": "Dataset",
"description": "User upload datasets."
}
},
{
"type": "null"
}
],
"title": "Dataset Names"
}
},
{
"name": "output_format",
"in": "query",
"required": false,
"schema": {
"enum": [
"csv",
"parquet"
],
"type": "string",
"default": "csv",
"title": "Output Format"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Variable Query (/api/datasets/download_variable_query_projects__team_id___project_id__datasets__dataset_id__variable_data_query_post)
Download dataset variable data — POST variant for large filter payloads.
## POST /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/variable_data_query
Download Variable Query
Download dataset variable data — POST variant for large filter payloads.
```json
{
"tags": [
"Datasets"
],
"summary": "Download Variable Query",
"description": "Download dataset variable data — POST variant for large filter payloads.",
"operationId": "download_variable_query_projects__team_id___project_id__datasets__dataset_id__variable_data_query_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"data_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Data Filters"
},
"dataset_names": {
"anyOf": [
{
"items": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra"
],
"title": "Dataset",
"description": "User upload datasets."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Dataset Names"
}
},
"type": "object",
"title": "VariableDataBody",
"description": "Request body for variable data _query endpoints."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Archive (/api/datasets/download_archive_projects__team_id___project_id__datasets__dataset_id__archive_get)
Download dataset as a zip file.
Retrieves a specific dataset in a project as a zip file containing
CSV-formatted data.
## GET /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/archive
Download Archive
Download dataset as a zip file.
Retrieves a specific dataset in a project as a zip file containing
CSV-formatted data.
```json
{
"tags": [
"Datasets"
],
"summary": "Download Archive",
"description": "Download dataset as a zip file.\n\nRetrieves a specific dataset in a project as a zip file containing\nCSV-formatted data.",
"operationId": "download_archive_projects__team_id___project_id__datasets__dataset_id__archive_get",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Variables (/api/datasets/list_variables_projects__team_id___project_id__datasets__dataset_id__variable_get)
List dataset variables.
Retrieves available variables for a specific dataset in a project,
formatted by the set function.
## GET /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/variable
List Variables
List dataset variables.
Retrieves available variables for a specific dataset in a project,
formatted by the set function.
```json
{
"tags": [
"Datasets"
],
"summary": "List Variables",
"description": "List dataset variables.\n\nRetrieves available variables for a specific dataset in a project,\nformatted by the set function.",
"operationId": "list_variables_projects__team_id___project_id__datasets__dataset_id__variable_get",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "set_fn",
"in": "query",
"required": false,
"schema": {
"enum": [
"union",
"grouped",
"intersect"
],
"type": "string",
"default": "union",
"title": "Set Fn"
}
},
{
"name": "combinations",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"properties": {
"country_code": {
"type": "string",
"title": "Country Code"
},
"region_code": {
"type": "string",
"title": "Region Code"
},
"grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"country_code",
"region_code",
"grouping"
],
"title": "ModellingCombinationBaseModel",
"description": "Schema for getting modelling combination (BaseModel)."
}
},
{
"type": "null"
}
],
"description": "List of modelling combinations to get variables for.",
"title": "Combinations"
},
"description": "List of modelling combinations to get variables for."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid",
"description": "Variable identifier"
},
"Slug": {
"type": "string",
"title": "Slug",
"description": "Unique variable key in format 'source-type-attributes'"
},
"Name": {
"type": "string",
"title": "Name",
"description": "Human-readable display name"
},
"Type": {
"description": "Variable category: Sales, Media, Macro, Price, etc.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes"
},
"Group": {
"description": "Functional grouping: KPI, Input, Volume, etc.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups"
},
"MinLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Minlimit",
"description": "Project-level lower bound for this variable. Used as the attribution reference point and as a hard lower bound on user-supplied values in simulation/prediction/optimization/response-curve/attribution-baseline inputs. NULL means no enforced lower bound."
},
"MaxLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Maxlimit",
"description": "Project-level upper bound for this variable. Hard upper bound on user-supplied values in simulation/prediction/optimization/response-curve/attribution-baseline inputs. NULL means no enforced upper bound."
},
"util_attr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
],
"description": "Parsed variable attributes (Product, Media, Campaign, etc.)"
}
},
"type": "object",
"required": [
"IId",
"Slug",
"Name",
"Type",
"Group"
],
"title": "Variable",
"description": "Response schema for variable metadata.",
"examples": [
{
"Group": "Sales",
"IId": 1,
"Name": "Health Units Sold",
"Slug": "file-sales-product-health-metric-units_sold",
"Type": "Sales",
"util_attr": {
"Metric": "UnitsSold",
"Product": "Health"
}
}
]
}
},
{
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"title": "Response List Variables Projects Team Id Project Id Datasets Dataset Id Variable Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Variables Post (/api/datasets/list_variables_post__projects__team_id___project_id__datasets__dataset_id__variable_post)
List dataset variables.
Retrieves available variables for a specific dataset in a project,
formatted by the set function.
## POST /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/variable
List Variables Post
List dataset variables.
Retrieves available variables for a specific dataset in a project,
formatted by the set function.
```json
{
"tags": [
"Datasets"
],
"summary": "List Variables Post ",
"description": "List dataset variables.\n\nRetrieves available variables for a specific dataset in a project,\nformatted by the set function.",
"operationId": "list_variables_post__projects__team_id___project_id__datasets__dataset_id__variable_post",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "set_fn",
"in": "query",
"required": false,
"schema": {
"enum": [
"union",
"grouped",
"intersec"
],
"type": "string",
"default": "union",
"title": "Set Fn"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"properties": {
"country_code": {
"type": "string",
"title": "Country Code"
},
"region_code": {
"type": "string",
"title": "Region Code"
},
"grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"country_code",
"region_code",
"grouping"
],
"title": "ModellingCombinationBaseModel",
"description": "Schema for getting modelling combination (BaseModel)."
}
},
{
"type": "null"
}
],
"title": "Modelling Combinations"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid",
"description": "Variable identifier"
},
"Slug": {
"type": "string",
"title": "Slug",
"description": "Unique variable key in format 'source-type-attributes'"
},
"Name": {
"type": "string",
"title": "Name",
"description": "Human-readable display name"
},
"Type": {
"description": "Variable category: Sales, Media, Macro, Price, etc.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes"
},
"Group": {
"description": "Functional grouping: KPI, Input, Volume, etc.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups"
},
"MinLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Minlimit",
"description": "Project-level lower bound for this variable. Used as the attribution reference point and as a hard lower bound on user-supplied values in simulation/prediction/optimization/response-curve/attribution-baseline inputs. NULL means no enforced lower bound."
},
"MaxLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Maxlimit",
"description": "Project-level upper bound for this variable. Hard upper bound on user-supplied values in simulation/prediction/optimization/response-curve/attribution-baseline inputs. NULL means no enforced upper bound."
},
"util_attr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
],
"description": "Parsed variable attributes (Product, Media, Campaign, etc.)"
}
},
"type": "object",
"required": [
"IId",
"Slug",
"Name",
"Type",
"Group"
],
"title": "Variable",
"description": "Response schema for variable metadata.",
"examples": [
{
"Group": "Sales",
"IId": 1,
"Name": "Health Units Sold",
"Slug": "file-sales-product-health-metric-units_sold",
"Type": "Sales",
"util_attr": {
"Metric": "UnitsSold",
"Product": "Health"
}
}
]
}
},
{
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"title": "Response List Variables Post Projects Team Id Project Id Datasets Dataset Id Variable Post"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Variable Importance (/api/datasets/list_variable_importance_projects__team_id___project_id__datasets__dataset_id__importantce_post)
List variable importance for a dataset.
Calculates importance of variables in a dataset for a model within a
project, using specified settings.
## POST /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/importantce
List Variable Importance
List variable importance for a dataset.
Calculates importance of variables in a dataset for a model within a
project, using specified settings.
```json
{
"tags": [
"Datasets"
],
"summary": "List Variable Importance",
"description": "List variable importance for a dataset.\n\nCalculates importance of variables in a dataset for a model within a\nproject, using specified settings.",
"operationId": "list_variable_importance_projects__team_id___project_id__datasets__dataset_id__importantce_post",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "country_code",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Three letters of country code",
"title": "Country Code"
},
"description": "Three letters of country code"
},
{
"name": "region_code",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Region code",
"title": "Region Code"
},
"description": "Region code"
},
{
"name": "grouping",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Grouping",
"title": "Grouping"
},
"description": "Grouping"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"targets": {
"items": {
"type": "string"
},
"type": "array",
"minItems": 1,
"title": "Targets"
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"minItems": 1
},
{
"type": "null"
}
],
"title": "Variables"
},
"quantiles": {
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array",
"minItems": 1,
"title": "Quantiles",
"default": [
10,
25,
50,
75,
90
]
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Start Date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "End Date"
}
},
"type": "object",
"required": [
"targets"
],
"title": "DataSetImportance",
"description": "Schema for dataset importance request."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Variable Correlation (/api/datasets/list_variable_correlation_projects__team_id___project_id__datasets__dataset_id__correlation_post)
List variable correlation for a dataset.
Calculates correlation of variables in a dataset for a model within
a project, using specified settings.
## POST /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/correlation
List Variable Correlation
List variable correlation for a dataset.
Calculates correlation of variables in a dataset for a model within
a project, using specified settings.
```json
{
"tags": [
"Datasets"
],
"summary": "List Variable Correlation",
"description": "List variable correlation for a dataset.\n\nCalculates correlation of variables in a dataset for a model within\na project, using specified settings.",
"operationId": "list_variable_correlation_projects__team_id___project_id__datasets__dataset_id__correlation_post",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "country_code",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Three letters of country code",
"title": "Country Code"
},
"description": "Three letters of country code"
},
{
"name": "region_code",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Region code",
"title": "Region Code"
},
"description": "Region code"
},
{
"name": "grouping",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Grouping",
"title": "Grouping"
},
"description": "Grouping"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"targets": {
"items": {
"type": "string"
},
"type": "array",
"minItems": 1,
"title": "Targets"
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"minItems": 1
},
{
"type": "null"
}
],
"title": "Variables"
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Start Date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "End Date"
}
},
"type": "object",
"required": [
"targets"
],
"title": "DataSetCorrelationRequest",
"description": "Schema for dataset correlation request."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Modelling Combinations (/api/datasets/list_modelling_combinations_projects__team_id___project_id__datasets__dataset_id__modelling_combinations_get)
List modelling combinations for a dataset.
This endpoint retrieves the intersection or union of all modelling combinations
(Country/Region/Grouping) across the specified datasets within a project.
## GET /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/modelling_combinations
List Modelling Combinations
List modelling combinations for a dataset.
This endpoint retrieves the intersection or union of all modelling combinations
(Country/Region/Grouping) across the specified datasets within a project.
```json
{
"tags": [
"Datasets"
],
"summary": "List Modelling Combinations",
"description": "List modelling combinations for a dataset.\n\nThis endpoint retrieves the intersection or union of all modelling combinations\n(Country/Region/Grouping) across the specified datasets within a project.",
"operationId": "list_modelling_combinations_projects__team_id___project_id__datasets__dataset_id__modelling_combinations_get",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "dataset_names",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"title": "Dataset Names"
}
},
{
"name": "column_names",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"enum": [
"Country",
"Region",
"Grouping"
],
"type": "string"
},
"default": [
"Country",
"Region",
"Grouping"
],
"title": "Column Names"
}
},
{
"name": "join_op",
"in": "query",
"required": false,
"schema": {
"enum": [
"union",
"intersect",
"both"
],
"type": "string",
"default": "union",
"title": "Join Op"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string"
}
}
}
],
"title": "Response List Modelling Combinations Projects Team Id Project Id Datasets Dataset Id Modelling Combinations Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Dates (/api/datasets/get_dates_projects__team_id___project_id__datasets__dataset_id__dates_get)
List dates for a dataset for a single modelling combination.
This endpoint retrieves the intersection of dates across the specified datasets
for a single modelling combination within a project. Optionally, the dates can be
extended by a specified percentage.
## GET /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/dates
Get Dates
List dates for a dataset for a single modelling combination.
This endpoint retrieves the intersection of dates across the specified datasets
for a single modelling combination within a project. Optionally, the dates can be
extended by a specified percentage.
```json
{
"tags": [
"Datasets"
],
"summary": "Get Dates",
"description": "List dates for a dataset for a single modelling combination.\n\nThis endpoint retrieves the intersection of dates across the specified datasets\nfor a single modelling combination within a project. Optionally, the dates can be\nextended by a specified percentage.",
"operationId": "get_dates_projects__team_id___project_id__datasets__dataset_id__dates_get",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "dataset_names",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"title": "Dataset Names"
}
},
{
"name": "country_code",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Three letters of country code",
"title": "Country Code"
},
"description": "Three letters of country code"
},
{
"name": "region_code",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Region code",
"title": "Region Code"
},
"description": "Region code"
},
{
"name": "grouping",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Grouping",
"title": "Grouping"
},
"description": "Grouping"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Dates Multiple Modeling Combintions (/api/datasets/get_dates_multiple_modeling_combintions_projects__team_id___project_id__datasets__dataset_id__dates_post)
Get dates for multiple modelling combinations.
This endpoint retrieves the intersection of dates across the specified datasets and
modelling combinations within a project. Optionally, the dates can be extended by a
specified percentage.
## POST /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/dates
Get Dates Multiple Modeling Combintions
Get dates for multiple modelling combinations.
This endpoint retrieves the intersection of dates across the specified datasets and
modelling combinations within a project. Optionally, the dates can be extended by a
specified percentage.
```json
{
"tags": [
"Datasets"
],
"summary": "Get Dates Multiple Modeling Combintions",
"description": "Get dates for multiple modelling combinations.\n\nThis endpoint retrieves the intersection of dates across the specified datasets and\nmodelling combinations within a project. Optionally, the dates can be extended by a\nspecified percentage.",
"operationId": "get_dates_multiple_modeling_combintions_projects__team_id___project_id__datasets__dataset_id__dates_post",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "dataset_names",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"title": "Dataset Names"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"properties": {
"country_code": {
"type": "string",
"title": "Country Code"
},
"region_code": {
"type": "string",
"title": "Region Code"
},
"grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"country_code",
"region_code",
"grouping"
],
"title": "ModellingCombinationBaseModel",
"description": "Schema for getting modelling combination (BaseModel)."
}
},
{
"type": "null"
}
],
"title": "Modelling Combinations"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Dataset Dates Min Max (/api/datasets/get_dataset_dates_min_max_projects__team_id___project_id__datasets__dataset_id__dates_min_max_get)
Get min and max dates from dataset data.
## GET /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/dates_min_max
Get Dataset Dates Min Max
Get min and max dates from dataset data.
```json
{
"tags": [
"Datasets"
],
"summary": "Get Dataset Dates Min Max",
"description": "Get min and max dates from dataset data.",
"operationId": "get_dataset_dates_min_max_projects__team_id___project_id__datasets__dataset_id__dates_min_max_get",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"min": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Min"
},
"max": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Max"
}
},
"type": "object",
"required": [
"min",
"max"
],
"title": "DateRange",
"description": "Min and max dates for a resource collection."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Valid Models (/api/datasets/list_valid_models_projects__team_id___project_id__datasets__dataset_id__valid_models_get)
List of valid models for a dataset.
Retrieves valid machine learning models for a dataset in a project,
with optional model ID filters.
## GET /api/projects/{team_id}/{project_id}/datasets/{dataset_id}/valid_models
List Valid Models
List of valid models for a dataset.
Retrieves valid machine learning models for a dataset in a project,
with optional model ID filters.
```json
{
"tags": [
"Datasets"
],
"summary": "List Valid Models",
"description": "List of valid models for a dataset.\n\nRetrieves valid machine learning models for a dataset in a project,\nwith optional model ID filters.",
"operationId": "list_valid_models_projects__team_id___project_id__datasets__dataset_id__valid_models_get",
"parameters": [
{
"name": "dataset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset.",
"title": "Dataset Id"
},
"description": "Use the dataset scoped id or the keyword 'active' to use active dataset."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "model_ids",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "integer"
}
},
{
"type": "null"
}
],
"title": "Model Ids"
}
},
{
"name": "country_code",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Three letters of country code",
"title": "Country Code"
},
"description": "Three letters of country code"
},
{
"name": "region_code",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Region code",
"title": "Region Code"
},
"description": "Region code"
},
{
"name": "grouping",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Grouping",
"title": "Grouping"
},
"description": "Grouping"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active model for its market segment"
},
"Country": {
"type": "string",
"title": "Country",
"description": "Country code from modelling combination (e.g., 'USA', 'GBR')"
},
"Region": {
"type": "string",
"title": "Region",
"description": "Region code from modelling combination (e.g., 'all', 'northeast')"
},
"Grouping": {
"type": "string",
"title": "Grouping",
"description": "Grouping code from modelling combination (e.g., 'all', 'retail')"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Model training completion timestamp"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Selected",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "Models",
"description": "Response schema for trained models listing and summary views.",
"examples": [
{
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Grouping": "all",
"IId": 1,
"JobId": 123,
"Name": "USA All Model",
"Note": "Model for USA market",
"Region": "all",
"Selected": true,
"Status": "completed"
}
]
},
"title": "Response List Valid Models Projects Team Id Project Id Datasets Dataset Id Valid Models Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Feature Importance (/api/feature-importance/list_feature_importance_projects__team_id___project_id__importance_get)
List feature importance jobs.
Retrieves a paginated list of jobs calculating feature importance
for models in a project, with optional filters.
## GET /api/projects/{team_id}/{project_id}/importance
List Feature Importance
List feature importance jobs.
Retrieves a paginated list of jobs calculating feature importance
for models in a project, with optional filters.
```json
{
"tags": [
"Feature Importance"
],
"summary": "List Feature Importance",
"description": "List feature importance jobs.\n\nRetrieves a paginated list of jobs calculating feature importance\nfor models in a project, with optional filters.",
"operationId": "list_feature_importance_projects__team_id___project_id__importance_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - Recent jobs: filters='{\"Date\": [[\">=\", \"2024-10-01\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - Recent jobs: filters='{\"Date\": [[\">=\", \"2024-10-01\"]]}'\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier for the feature importance job"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
}
},
"type": "object",
"required": [
"IId",
"Status"
],
"title": "FeatureImportance",
"description": "Response schema for feature importance analysis jobs."
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[FeatureImportance]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Submit Feature Importance Calculation (/api/feature-importance/submit_feature_importance_calculation_projects__team_id___project_id__importance_post)
Submit a feature importance job.
Creates a job to calculate feature importance for variables in a
dataset using a model within a project.
## POST /api/projects/{team_id}/{project_id}/importance
Submit Feature Importance Calculation
Submit a feature importance job.
Creates a job to calculate feature importance for variables in a
dataset using a model within a project.
```json
{
"tags": [
"Feature Importance"
],
"summary": "Submit Feature Importance Calculation",
"description": "Submit a feature importance job.\n\nCreates a job to calculate feature importance for variables in a\ndataset using a model within a project.",
"operationId": "submit_feature_importance_calculation_projects__team_id___project_id__importance_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "country_code",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Three letters of country code",
"title": "Country Code"
},
"description": "Three letters of country code"
},
{
"name": "region_code",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Region code",
"title": "Region Code"
},
"description": "Region code"
},
{
"name": "grouping",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Grouping",
"title": "Grouping"
},
"description": "Grouping"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"targets": {
"items": {
"type": "string"
},
"type": "array",
"minItems": 1,
"title": "Targets"
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array",
"minItems": 1
},
{
"type": "null"
}
],
"title": "Variables"
},
"quantiles": {
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array",
"minItems": 1,
"title": "Quantiles",
"default": [
10,
25,
50,
75,
90
]
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Start Date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "End Date"
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
}
},
"type": "object",
"required": [
"targets",
"dataset_id"
],
"title": "DataSetImportanceJobRequest",
"description": "Schema for dataset importance job request."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier for the feature importance job"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
}
},
"type": "object",
"required": [
"IId",
"Status"
],
"title": "FeatureImportance",
"description": "Response schema for feature importance analysis jobs."
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Feature Importance (/api/feature-importance/get_feature_importance_projects__team_id___project_id__importance__importance_id__get)
Get details of a feature importance job.
Retrieves detailed information about a job calculating feature
importance for a model in a project.
## GET /api/projects/{team_id}/{project_id}/importance/{importance_id}
Get Feature Importance
Get details of a feature importance job.
Retrieves detailed information about a job calculating feature
importance for a model in a project.
```json
{
"tags": [
"Feature Importance"
],
"summary": "Get Feature Importance",
"description": "Get details of a feature importance job.\n\nRetrieves detailed information about a job calculating feature\nimportance for a model in a project.",
"operationId": "get_feature_importance_projects__team_id___project_id__importance__importance_id__get",
"parameters": [
{
"name": "importance_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide feature importance job IId.",
"title": "Importance Id"
},
"description": "Provide feature importance job IId."
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"Task": {
"anyOf": [
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"Topic": {
"type": "string",
"enum": [
"ATTRIBUTIONSET",
"ATTRIBUTIONJOB",
"SIMULATIONJOB",
"PREDICTIONJOB",
"TRAINJOB",
"DATASET",
"DATAUPLOAD",
"GRAPHCONSTRUCT",
"GENERAL",
"OPTIMIZATIONJOB",
"RESPOSNSECURVEJOB",
"PRIORPOSTERIORJOB",
"EXCELJOB",
"GRAPHBASIC",
"FEATUREIMPORTANCE",
"GRAPHSYNERGY"
],
"title": "TaskTopics",
"description": "Task topics."
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"Id",
"Config",
"Topic",
"Status"
],
"title": "Task",
"description": "Reference task."
},
{
"type": "null"
}
]
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier for the feature importance job"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Quantiles": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Quantiles",
"description": "Uncertainty quantiles computed"
},
"Targets": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"Slug": {
"type": "string",
"title": "Slug"
},
"Type": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes",
"description": "Varaible Tyeps."
},
"Group": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups",
"description": "Vraible groups."
}
},
"type": "object",
"required": [
"IId",
"Name",
"Slug",
"Type",
"Group"
],
"title": "VariableRef",
"description": "Variable reference."
},
"type": "array",
"title": "Targets",
"description": "Target variables analyzed"
},
"Variables": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"Slug": {
"type": "string",
"title": "Slug"
},
"Type": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes",
"description": "Varaible Tyeps."
},
"Group": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups",
"description": "Vraible groups."
}
},
"type": "object",
"required": [
"IId",
"Name",
"Slug",
"Type",
"Group"
],
"title": "VariableRef",
"description": "Variable reference."
},
"type": "array",
"title": "Variables",
"description": "Input variables with importance scores"
}
},
"type": "object",
"required": [
"IId",
"Status",
"Targets",
"Variables"
],
"title": "DetailedFeatureImportance",
"description": "Detailed response schema for feature importance analysis jobs."
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Feature Importance (/api/feature-importance/delete_feature_importance_projects__team_id___project_id__importance__importance_id__delete)
Delete a feature importance job.
Removes a specific job calculating feature importance for a model
from a project.
## DELETE /api/projects/{team_id}/{project_id}/importance/{importance_id}
Delete Feature Importance
Delete a feature importance job.
Removes a specific job calculating feature importance for a model
from a project.
```json
{
"tags": [
"Feature Importance"
],
"summary": "Delete Feature Importance",
"description": "Delete a feature importance job.\n\nRemoves a specific job calculating feature importance for a model\nfrom a project.",
"operationId": "delete_feature_importance_projects__team_id___project_id__importance__importance_id__delete",
"parameters": [
{
"name": "importance_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide feature importance job IId.",
"title": "Importance Id"
},
"description": "Provide feature importance job IId."
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Feature Importance (/api/feature-importance/download_feature_importance_projects__team_id___project_id__importance__importance_id__data_get)
Download feature importance job data.
Retrieves data for a feature importance job of a model in a project,
with optional filters like country.
## GET /api/projects/{team_id}/{project_id}/importance/{importance_id}/data
Download Feature Importance
Download feature importance job data.
Retrieves data for a feature importance job of a model in a project,
with optional filters like country.
```json
{
"tags": [
"Feature Importance"
],
"summary": "Download Feature Importance",
"description": "Download feature importance job data.\n\nRetrieves data for a feature importance job of a model in a project,\nwith optional filters like country.",
"operationId": "download_feature_importance_projects__team_id___project_id__importance__importance_id__data_get",
"parameters": [
{
"name": "importance_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide feature importance job IId.",
"title": "Importance Id"
},
"description": "Provide feature importance job IId."
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "result_filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n Filter feature importance result data rows.\n\n Examples:\n - By country: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"media\"]]}'\n ",
"title": "Result Filters"
},
"description": "\n Filter feature importance result data rows.\n\n Examples:\n - By country: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"media\"]]}'\n "
},
{
"name": "output_format",
"in": "query",
"required": false,
"schema": {
"enum": [
"csv",
"parquet"
],
"type": "string",
"default": "csv",
"title": "Output Format"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Variable Overwrites (/api/variables/list_variable_overwrites_projects__team_id___project_id__variable_overwrites_get)
List variable overwrites for a variable.
## GET /api/projects/{team_id}/{project_id}/variable_overwrites
List Variable Overwrites
List variable overwrites for a variable.
```json
{
"tags": [
"Variables"
],
"summary": "List Variable Overwrites",
"description": "List variable overwrites for a variable.",
"operationId": "list_variable_overwrites_projects__team_id___project_id__variable_overwrites_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "\n Usage:\n - filters='{\"IId\" : [[ \"in\", \"[1,2,3]\"]]}'\n - filters='{\"Slug\" : [[ \"contains\", \"term\"]]}'\n ",
"title": "Filters"
},
"description": "\n Usage:\n - filters='{\"IId\" : [[ \"in\", \"[1,2,3]\"]]}'\n - filters='{\"Slug\" : [[ \"contains\", \"term\"]]}'\n "
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"VarIId": {
"type": "integer",
"title": "Variid"
},
"Slug": {
"type": "string",
"title": "Slug"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"Profit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Profit"
},
"Price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Price"
}
},
"type": "object",
"required": [
"VarIId",
"Slug",
"Country",
"Region",
"Grouping"
],
"title": "VariableOverwrite",
"description": "Schema for variable overwrite."
},
"title": "Response List Variable Overwrites Projects Team Id Project Id Variable Overwrites Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Post Variable Overwrites (/api/variables/post_variable_overwrites_projects__team_id___project_id__variable_overwrites_post)
Add variable overwrites in a project.
you can bulk upsert variable overwrites by passing a list of objects with VarIId, Combinations, Price and Profit.
if both Price and Profit are null, the overwrite will be deleted.
Example:
```
[
// Created or Updated
{"VarIId": 1, "Country": "DEN", "Region": "all", "Grouping": "all", "Price": 100.0, "Profit": 20.0},
// Deleted
{"VarIId": 1, "Country": "DEN", "Region": "all", "Grouping": "all", "Price": null, "Profit": null},
]
```
## POST /api/projects/{team_id}/{project_id}/variable_overwrites
Post Variable Overwrites
Add variable overwrites in a project.
you can bulk upsert variable overwrites by passing a list of objects with VarIId, Combinations, Price and Profit.
if both Price and Profit are null, the overwrite will be deleted.
Example:
```
[
// Created or Updated
{"VarIId": 1, "Country": "DEN", "Region": "all", "Grouping": "all", "Price": 100.0, "Profit": 20.0},
// Deleted
{"VarIId": 1, "Country": "DEN", "Region": "all", "Grouping": "all", "Price": null, "Profit": null},
]
```
```json
{
"tags": [
"Variables"
],
"summary": "Post Variable Overwrites",
"description": "Add variable overwrites in a project.\n\nyou can bulk upsert variable overwrites by passing a list of objects with VarIId, Combinations, Price and Profit.\nif both Price and Profit are null, the overwrite will be deleted.\n\nExample:\n```\n[\n // Created or Updated\n {\"VarIId\": 1, \"Country\": \"DEN\", \"Region\": \"all\", \"Grouping\": \"all\", \"Price\": 100.0, \"Profit\": 20.0},\n // Deleted\n {\"VarIId\": 1, \"Country\": \"DEN\", \"Region\": \"all\", \"Grouping\": \"all\", \"Price\": null, \"Profit\": null},\n]\n```",
"operationId": "post_variable_overwrites_projects__team_id___project_id__variable_overwrites_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"VarIId": {
"type": "integer",
"title": "Variid",
"description": "Variable IId."
},
"Country": {
"type": "string",
"title": "Country",
"description": "Country code."
},
"Region": {
"type": "string",
"title": "Region",
"description": "Region code."
},
"Grouping": {
"type": "string",
"title": "Grouping",
"description": "Grouping code."
},
"Profit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Profit",
"description": "Change Profit overwrite."
},
"Price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Price",
"description": "Change Price overwrite."
}
},
"type": "object",
"required": [
"VarIId",
"Country",
"Region",
"Grouping"
],
"title": "PostVariableOverwrite",
"description": "Schema for posting variable overwrite settings."
},
"title": "Body"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"VarIId": {
"type": "integer",
"title": "Variid"
},
"Slug": {
"type": "string",
"title": "Slug"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"Profit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Profit"
},
"Price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Price"
}
},
"type": "object",
"required": [
"VarIId",
"Slug",
"Country",
"Region",
"Grouping"
],
"title": "VariableOverwrite",
"description": "Schema for variable overwrite."
},
"title": "Response Post Variable Overwrites Projects Team Id Project Id Variable Overwrites Post"
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Variables (/api/variables/list_variables_projects__team_id___project_id__variables_get)
List variables.
This endpoint retrieves a paginated list of variables based on the provided filters
within a specified project.
## GET /api/projects/{team_id}/{project_id}/variables
List Variables
List variables.
This endpoint retrieves a paginated list of variables based on the provided filters
within a specified project.
```json
{
"tags": [
"Variables"
],
"summary": "List Variables",
"description": "List variables.\n\nThis endpoint retrieves a paginated list of variables based on the provided filters\nwithin a specified project.",
"operationId": "list_variables_projects__team_id___project_id__variables_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By name: filters='{\"Name\": [[\"contains\", \"Sales\"]]}'\n - By slug: filters='{\"Slug\": [[\"contains\", \"media-tv\"]]}'\n - By type: filters='{\"Type\": [[\"=\", \"Media\"]]}'\n - By group: filters='{\"Group\": [[\"=\", \"KPI\"]]}'\n - Multiple types: filters='{\"Type\": [[\"in\", \"[\\\"Media\\\", \\\"Sales\\\"]\"]]}'\n - Name search: filters='{\"Name\": [[\"similarity\", \"television\"]]}'\n\n Operators: =, !=, contains, startswith, endswith, ilike, in, notin, similarity\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By name: filters='{\"Name\": [[\"contains\", \"Sales\"]]}'\n - By slug: filters='{\"Slug\": [[\"contains\", \"media-tv\"]]}'\n - By type: filters='{\"Type\": [[\"=\", \"Media\"]]}'\n - By group: filters='{\"Group\": [[\"=\", \"KPI\"]]}'\n - Multiple types: filters='{\"Type\": [[\"in\", \"[\\\"Media\\\", \\\"Sales\\\"]\"]]}'\n - Name search: filters='{\"Name\": [[\"similarity\", \"television\"]]}'\n\n Operators: =, !=, contains, startswith, endswith, ilike, in, notin, similarity\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid",
"description": "Variable identifier"
},
"Slug": {
"type": "string",
"title": "Slug",
"description": "Unique variable key in format 'source-type-attributes'"
},
"Name": {
"type": "string",
"title": "Name",
"description": "Human-readable display name"
},
"Type": {
"description": "Variable category: Sales, Media, Macro, Price, etc.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes"
},
"Group": {
"description": "Functional grouping: KPI, Input, Volume, etc.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups"
},
"MinLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Minlimit",
"description": "Project-level lower bound for this variable. Used as the attribution reference point and as a hard lower bound on user-supplied values in simulation/prediction/optimization/response-curve/attribution-baseline inputs. NULL means no enforced lower bound."
},
"MaxLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Maxlimit",
"description": "Project-level upper bound for this variable. Hard upper bound on user-supplied values in simulation/prediction/optimization/response-curve/attribution-baseline inputs. NULL means no enforced upper bound."
},
"util_attr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
],
"description": "Parsed variable attributes (Product, Media, Campaign, etc.)"
}
},
"type": "object",
"required": [
"IId",
"Slug",
"Name",
"Type",
"Group"
],
"title": "Variable",
"description": "Response schema for variable metadata.",
"examples": [
{
"Group": "Sales",
"IId": 1,
"Name": "Health Units Sold",
"Slug": "file-sales-product-health-metric-units_sold",
"Type": "Sales",
"util_attr": {
"Metric": "UnitsSold",
"Product": "Health"
}
}
]
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[Variable]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Varaible (/api/variables/update_varaible_projects__team_id___project_id__variables__var_id__patch)
Update a variable.
This endpoint updates the attributes of an existing variable based on the provided
update data.
## PATCH /api/projects/{team_id}/{project_id}/variables/{var_id}
Update Varaible
Update a variable.
This endpoint updates the attributes of an existing variable based on the provided
update data.
```json
{
"tags": [
"Variables"
],
"summary": "Update Varaible",
"description": "Update a variable.\n\nThis endpoint updates the attributes of an existing variable based on the provided\nupdate data.",
"operationId": "update_varaible_projects__team_id___project_id__variables__var_id__patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "var_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Variable IId.",
"title": "Var Id"
},
"description": "Variable IId."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"MinLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Minlimit",
"description": "Lower bound for this variable. Send `null` to clear. The DB enforces MinLimit < MaxLimit when both are set."
},
"MaxLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Maxlimit",
"description": "Upper bound for this variable. Send `null` to clear. The DB enforces MinLimit < MaxLimit when both are set."
}
},
"type": "object",
"title": "PatchVariable",
"description": "Schema for updating variable.\n\nAny combination of fields may be supplied; only fields present in the request\nbody are applied. To clear a limit, send the field explicitly as `null`.",
"examples": [
{
"MaxLimit": 100000,
"MinLimit": 0,
"Name": "TV Advertising Spend"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid",
"description": "Variable identifier"
},
"Slug": {
"type": "string",
"title": "Slug",
"description": "Unique variable key in format 'source-type-attributes'"
},
"Name": {
"type": "string",
"title": "Name",
"description": "Human-readable display name"
},
"Type": {
"description": "Variable category: Sales, Media, Macro, Price, etc.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes"
},
"Group": {
"description": "Functional grouping: KPI, Input, Volume, etc.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups"
},
"MinLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Minlimit",
"description": "Project-level lower bound for this variable. Used as the attribution reference point and as a hard lower bound on user-supplied values in simulation/prediction/optimization/response-curve/attribution-baseline inputs. NULL means no enforced lower bound."
},
"MaxLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Maxlimit",
"description": "Project-level upper bound for this variable. Hard upper bound on user-supplied values in simulation/prediction/optimization/response-curve/attribution-baseline inputs. NULL means no enforced upper bound."
},
"util_attr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
],
"description": "Parsed variable attributes (Product, Media, Campaign, etc.)"
}
},
"type": "object",
"required": [
"IId",
"Slug",
"Name",
"Type",
"Group"
],
"title": "Variable",
"description": "Response schema for variable metadata.",
"examples": [
{
"Group": "Sales",
"IId": 1,
"Name": "Health Units Sold",
"Slug": "file-sales-product-health-metric-units_sold",
"Type": "Sales",
"util_attr": {
"Metric": "UnitsSold",
"Product": "Health"
}
}
]
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Variable Util Overrides (/api/variables/list_variable_util_overrides_projects__team_id___project_id__variable_util_overrides_get)
List util_attr relabels for the project, optionally filtered by Type.
## GET /api/projects/{team_id}/{project_id}/variable_util_overrides
List Variable Util Overrides
List util_attr relabels for the project, optionally filtered by Type.
```json
{
"tags": [
"Variables"
],
"summary": "List Variable Util Overrides",
"description": "List util_attr relabels for the project, optionally filtered by Type.",
"operationId": "list_variable_util_overrides_projects__team_id___project_id__variable_util_overrides_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes",
"description": "Varaible Tyeps."
},
{
"type": "null"
}
],
"description": "Filter to one variable Type.",
"title": "Type"
},
"description": "Filter to one variable Type."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Type": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes",
"description": "Varaible Tyeps."
},
"Attribute": {
"type": "string",
"title": "Attribute"
},
"OriginalValue": {
"type": "string",
"title": "Originalvalue"
},
"OverrideValue": {
"type": "string",
"title": "Overridevalue"
}
},
"type": "object",
"required": [
"Type",
"Attribute",
"OriginalValue",
"OverrideValue"
],
"title": "VariableUtilOverride",
"description": "A per-type util_attr relabel.\n\nWithin variable ``Type``, attribute ``Attribute``'s base value\n``OriginalValue`` is displayed as ``OverrideValue`` for every variable of\nthat Type sharing the base value."
},
"title": "Response List Variable Util Overrides Projects Team Id Project Id Variable Util Overrides Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Post Variable Util Overrides (/api/variables/post_variable_util_overrides_projects__team_id___project_id__variable_util_overrides_post)
Bulk upsert per-type util_attr relabels.
Each item relabels one ``(Type, Attribute, OriginalValue)`` to
``OverrideValue``; a null ``OverrideValue`` deletes that relabel.
Example:
```
[
{"Type": "Brand", "Attribute": "Brand",
"OriginalValue": "b1", "OverrideValue": "b2"},
{"Type": "Brand", "Attribute": "Metric",
"OriginalValue": "m1", "OverrideValue": null}
]
```
## POST /api/projects/{team_id}/{project_id}/variable_util_overrides
Post Variable Util Overrides
Bulk upsert per-type util_attr relabels.
Each item relabels one ``(Type, Attribute, OriginalValue)`` to
``OverrideValue``; a null ``OverrideValue`` deletes that relabel.
Example:
```
[
{"Type": "Brand", "Attribute": "Brand",
"OriginalValue": "b1", "OverrideValue": "b2"},
{"Type": "Brand", "Attribute": "Metric",
"OriginalValue": "m1", "OverrideValue": null}
]
```
```json
{
"tags": [
"Variables"
],
"summary": "Post Variable Util Overrides",
"description": "Bulk upsert per-type util_attr relabels.\n\nEach item relabels one ``(Type, Attribute, OriginalValue)`` to\n``OverrideValue``; a null ``OverrideValue`` deletes that relabel.\n\nExample:\n```\n[\n {\"Type\": \"Brand\", \"Attribute\": \"Brand\",\n \"OriginalValue\": \"b1\", \"OverrideValue\": \"b2\"},\n {\"Type\": \"Brand\", \"Attribute\": \"Metric\",\n \"OriginalValue\": \"m1\", \"OverrideValue\": null}\n]\n```",
"operationId": "post_variable_util_overrides_projects__team_id___project_id__variable_util_overrides_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Type": {
"description": "Variable type, e.g. 'Brand'.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes"
},
"Attribute": {
"type": "string",
"title": "Attribute",
"description": "util_attr column, e.g. 'Brand'."
},
"OriginalValue": {
"type": "string",
"title": "Originalvalue",
"description": "Base (ingested) value to relabel."
},
"OverrideValue": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Overridevalue",
"description": "Display value; null deletes the relabel."
}
},
"type": "object",
"required": [
"Type",
"Attribute",
"OriginalValue"
],
"title": "PostVariableUtilOverride",
"description": "One per-type util_attr relabel (a bulk-upsert item).\n\nWithin ``Type``, attribute ``Attribute``'s base value ``OriginalValue`` is\ndisplayed as ``OverrideValue``. A null ``OverrideValue`` deletes that relabel."
},
"title": "Body"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Type": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes",
"description": "Varaible Tyeps."
},
"Attribute": {
"type": "string",
"title": "Attribute"
},
"OriginalValue": {
"type": "string",
"title": "Originalvalue"
},
"OverrideValue": {
"type": "string",
"title": "Overridevalue"
}
},
"type": "object",
"required": [
"Type",
"Attribute",
"OriginalValue",
"OverrideValue"
],
"title": "VariableUtilOverride",
"description": "A per-type util_attr relabel.\n\nWithin variable ``Type``, attribute ``Attribute``'s base value\n``OriginalValue`` is displayed as ``OverrideValue`` for every variable of\nthat Type sharing the base value."
},
"title": "Response Post Variable Util Overrides Projects Team Id Project Id Variable Util Overrides Post"
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Patch Variable Util Overrides (/api/variables/patch_variable_util_overrides_projects__team_id___project_id__variable_util_overrides__var_type__patch)
Set or clear util_attr relabels for a single variable Type.
Body maps ``{Attribute: {OriginalValue: OverrideValue}}``; a null
``OverrideValue`` clears that relabel. Returns the Type's relabels after the
change.
Example body for ``PATCH .../variable_util_overrides/Brand``:
```
{"Brand": {"b1": "b2"}, "Metric": {"m1": "Volume"}}
```
## PATCH /api/projects/{team_id}/{project_id}/variable_util_overrides/{var_type}
Patch Variable Util Overrides
Set or clear util_attr relabels for a single variable Type.
Body maps ``{Attribute: {OriginalValue: OverrideValue}}``; a null
``OverrideValue`` clears that relabel. Returns the Type's relabels after the
change.
Example body for ``PATCH .../variable_util_overrides/Brand``:
```
{"Brand": {"b1": "b2"}, "Metric": {"m1": "Volume"}}
```
```json
{
"tags": [
"Variables"
],
"summary": "Patch Variable Util Overrides",
"description": "Set or clear util_attr relabels for a single variable Type.\n\nBody maps ``{Attribute: {OriginalValue: OverrideValue}}``; a null\n``OverrideValue`` clears that relabel. Returns the Type's relabels after the\nchange.\n\nExample body for ``PATCH .../variable_util_overrides/Brand``:\n```\n{\"Brand\": {\"b1\": \"b2\"}, \"Metric\": {\"m1\": \"Volume\"}}\n```",
"operationId": "patch_variable_util_overrides_projects__team_id___project_id__variable_util_overrides__var_type__patch",
"parameters": [
{
"name": "var_type",
"in": "path",
"required": true,
"schema": {
"description": "Variable Type to relabel, e.g. 'Brand'.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes"
},
"description": "Variable Type to relabel, e.g. 'Brand'."
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"additionalProperties": {
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"type": "object"
},
"type": "object",
"title": "PatchVariableUtilOverride",
"description": "Relabels for one variable Type: ``{Attribute: {OriginalValue: OverrideValue}}``.\n\nA null ``OverrideValue`` deletes that relabel. Example:\n``{\"Brand\": {\"b1\": \"b2\"}, \"Metric\": {\"m1\": \"Volume\"}}``."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Type": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes",
"description": "Varaible Tyeps."
},
"Attribute": {
"type": "string",
"title": "Attribute"
},
"OriginalValue": {
"type": "string",
"title": "Originalvalue"
},
"OverrideValue": {
"type": "string",
"title": "Overridevalue"
}
},
"type": "object",
"required": [
"Type",
"Attribute",
"OriginalValue",
"OverrideValue"
],
"title": "VariableUtilOverride",
"description": "A per-type util_attr relabel.\n\nWithin variable ``Type``, attribute ``Attribute``'s base value\n``OriginalValue`` is displayed as ``OverrideValue`` for every variable of\nthat Type sharing the base value."
},
"title": "Response Patch Variable Util Overrides Projects Team Id Project Id Variable Util Overrides Var Type Patch"
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Graphs (/api/models/list_graphs_projects__team_id___project_id__build_graphs_get)
List saved graph structures for model building.
Graphs define the causal structure (nodes and edges) used for model training.
They can be reused across multiple models to ensure consistent methodology.
Query Parameters:
- filters: JSON filter expressions to narrow results
Example: '{"Id": [["=", "1"]]}'
Response:
Paginated list of graphs with their model instances.
Related:
- POST /build/graphs: Save a new graph
- POST /build/model: Use a graph to train a model
## GET /api/projects/{team_id}/{project_id}/build/graphs
List Graphs
List saved graph structures for model building.
Graphs define the causal structure (nodes and edges) used for model training.
They can be reused across multiple models to ensure consistent methodology.
Query Parameters:
- filters: JSON filter expressions to narrow results
Example: '{"Id": [["=", "1"]]}'
Response:
Paginated list of graphs with their model instances.
Related:
- POST /build/graphs: Save a new graph
- POST /build/model: Use a graph to train a model
```json
{
"tags": [
"Models"
],
"summary": "List Graphs",
"description": "List saved graph structures for model building.\n\nGraphs define the causal structure (nodes and edges) used for model training.\nThey can be reused across multiple models to ensure consistent methodology.\n\nQuery Parameters:\n - filters: JSON filter expressions to narrow results\n Example: '{\"Id\": [[\"=\", \"1\"]]}'\n\nResponse:\n Paginated list of graphs with their model instances.\n\nRelated:\n - POST /build/graphs: Save a new graph\n - POST /build/model: Use a graph to train a model",
"operationId": "list_graphs_projects__team_id___project_id__build_graphs_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By ID: filters='{\"Id\": [[\"=\", \"1\"]]}'\n - By instances job: filters='{\"InstancesJobId\": [[\"isnot\", \"NULL\"]]}'\n - Multiple IDs: filters='{\"Id\": [[\"in\", \"[1, 2, 3]\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By ID: filters='{\"Id\": [[\"=\", \"1\"]]}'\n - By instances job: filters='{\"InstancesJobId\": [[\"isnot\", \"NULL\"]]}'\n - Multiple IDs: filters='{\"Id\": [[\"in\", \"[1, 2, 3]\"]]}'\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id",
"description": "Graph identifier"
},
"Graph": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Graph",
"description": "Graph structure with nodes (variables) and edges (relationships)"
},
"InstancesJobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Instancesjobid",
"description": "Background job ID for graph instantiation"
},
"Instantions": {
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"HasFinished": {
"type": "boolean",
"title": "Hasfinished"
},
"Models": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
},
"type": "array",
"title": "Models"
}
},
"type": "object",
"required": [
"Id",
"HasFinished",
"Models"
],
"title": "GraphInstanceModel",
"description": "Reference schema for graph instantiations with model info."
},
"type": "array",
"title": "Instantions",
"description": "List of graph instances created from this graph"
}
},
"type": "object",
"required": [
"Id",
"Instantions"
],
"title": "Graphs",
"description": "Response schema for causal graph structures."
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[Graphs]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Save Graph (/api/models/save_graph_projects__team_id___project_id__build_graphs_post)
Save a graph structure for reuse in model building.
Graphs define causal relationships between variables using nodes (variables)
and edges (relationships). Save graphs to reuse across multiple models
or share methodology across team members.
Response:
The ID of the saved graph (use as graph_id in POST /build/model)
Related:
- GET /build/graphs: List saved graphs
- POST /build/model: Use graph_id to build a model
## POST /api/projects/{team_id}/{project_id}/build/graphs
Save Graph
Save a graph structure for reuse in model building.
Graphs define causal relationships between variables using nodes (variables)
and edges (relationships). Save graphs to reuse across multiple models
or share methodology across team members.
Response:
The ID of the saved graph (use as graph_id in POST /build/model)
Related:
- GET /build/graphs: List saved graphs
- POST /build/model: Use graph_id to build a model
```json
{
"tags": [
"Models"
],
"summary": "Save Graph",
"description": "Save a graph structure for reuse in model building.\n\nGraphs define causal relationships between variables using nodes (variables)\nand edges (relationships). Save graphs to reuse across multiple models\nor share methodology across team members.\n\nResponse:\n The ID of the saved graph (use as graph_id in POST /build/model)\n\nRelated:\n - GET /build/graphs: List saved graphs\n - POST /build/model: Use graph_id to build a model",
"operationId": "save_graph_projects__team_id___project_id__build_graphs_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"graph": {
"description": "Graph structure defining variable relationships for modeling. Contains 'nodes' (variables) and 'edges' (causal relationships between variables). Each node has type, id, and key; edges define source→target connections.",
"properties": {
"nodes": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Nodes"
},
"edges": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Edges"
}
},
"type": "object",
"required": [
"nodes",
"edges"
],
"title": "Graph"
}
},
"type": "object",
"required": [
"graph"
],
"title": "GraphRequest",
"description": "Request body for creating a new graph structure."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"description": "Invalid model build request: invalid graph, missing variables, conflicting dates, or invalid hyperparameters",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Project is in read-only state",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Graph (/api/models/get_graph_projects__team_id___project_id__build_graphs__graph_id__get)
Get a graph by ID.
This endpoint retrieves a graph by its ID within a specified project.
## GET /api/projects/{team_id}/{project_id}/build/graphs/{graph_id}
Get Graph
Get a graph by ID.
This endpoint retrieves a graph by its ID within a specified project.
```json
{
"tags": [
"Models"
],
"summary": "Get Graph",
"description": "Get a graph by ID.\n\nThis endpoint retrieves a graph by its ID within a specified project.",
"operationId": "get_graph_projects__team_id___project_id__build_graphs__graph_id__get",
"parameters": [
{
"name": "graph_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"title": "Graph Id"
}
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Model not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Graph (/api/models/update_graph_projects__team_id___project_id__build_graphs__graph_id__patch)
Update a graph.
This endpoint updates an existing graph with the provided data.
## PATCH /api/projects/{team_id}/{project_id}/build/graphs/{graph_id}
Update Graph
Update a graph.
This endpoint updates an existing graph with the provided data.
```json
{
"tags": [
"Models"
],
"summary": "Update Graph",
"description": "Update a graph.\n\nThis endpoint updates an existing graph with the provided data.",
"operationId": "update_graph_projects__team_id___project_id__build_graphs__graph_id__patch",
"parameters": [
{
"name": "graph_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"title": "Graph Id"
}
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"graph": {
"description": "graph instances which want to be updated, consist of node and edge",
"properties": {
"nodes": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Nodes"
},
"edges": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Edges"
}
},
"type": "object",
"required": [
"nodes",
"edges"
],
"title": "Graph"
}
},
"type": "object",
"required": [
"graph"
],
"title": "GraphUpdate",
"description": "Schemas of graph patch request endpoint, consist of graph."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Model not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Build A Model (/api/models/build_a_model_projects__team_id___project_id__build_model_post)
Train a new ML model for forecasting business KPIs.
Initiates model training using a causal graph structure and historical data.
Models learn relationships between input variables (media spend, pricing, etc.)
and target KPIs (sales, revenue, etc.) to enable forecasting and attribution.
Workflow:
1. Ensure you have a dataset with required variables (see POST /dataset)
2. Define the model graph (nodes/edges) or use graph_variables
3. Submit model build with this endpoint
4. Poll GET /models/{model_id} until Status is COMPLETED
5. Use the trained model for predictions, simulations, or optimizations
Response:
Returns the created model. Poll status until COMPLETED.
Related:
- GET /models/{model_id}: Poll training status
- POST /models/{model_id}/refit: Retrain with different data/parameters
- POST /predictions: Use trained model for forecasting
- POST /simulations: Use trained model for scenario analysis
## POST /api/projects/{team_id}/{project_id}/build/model
Build A Model
Train a new ML model for forecasting business KPIs.
Initiates model training using a causal graph structure and historical data.
Models learn relationships between input variables (media spend, pricing, etc.)
and target KPIs (sales, revenue, etc.) to enable forecasting and attribution.
Workflow:
1. Ensure you have a dataset with required variables (see POST /dataset)
2. Define the model graph (nodes/edges) or use graph_variables
3. Submit model build with this endpoint
4. Poll GET /models/{model_id} until Status is COMPLETED
5. Use the trained model for predictions, simulations, or optimizations
Response:
Returns the created model. Poll status until COMPLETED.
Related:
- GET /models/{model_id}: Poll training status
- POST /models/{model_id}/refit: Retrain with different data/parameters
- POST /predictions: Use trained model for forecasting
- POST /simulations: Use trained model for scenario analysis
```json
{
"tags": [
"Models"
],
"summary": "Build A Model",
"description": "Train a new ML model for forecasting business KPIs.\n\nInitiates model training using a causal graph structure and historical data.\nModels learn relationships between input variables (media spend, pricing, etc.)\nand target KPIs (sales, revenue, etc.) to enable forecasting and attribution.\n\nWorkflow:\n 1. Ensure you have a dataset with required variables (see POST /dataset)\n 2. Define the model graph (nodes/edges) or use graph_variables\n 3. Submit model build with this endpoint\n 4. Poll GET /models/{model_id} until Status is COMPLETED\n 5. Use the trained model for predictions, simulations, or optimizations\n\nResponse:\n Returns the created model. Poll status until COMPLETED.\n\nRelated:\n - GET /models/{model_id}: Poll training status\n - POST /models/{model_id}/refit: Retrain with different data/parameters\n - POST /predictions: Use trained model for forecasting\n - POST /simulations: Use trained model for scenario analysis",
"operationId": "build_a_model_projects__team_id___project_id__build_model_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"model_param": {
"anyOf": [
{
"properties": {
"epochs": {
"type": "integer",
"title": "The epochs",
"description": "Maximum training iterations. Model may stop earlier if early_stopping is configured. Higher values allow more learning but risk overfitting. Default (500) works for most models.",
"default": 500
},
"learning_rate": {
"type": "number",
"title": "The learning rate",
"description": "Step size for gradient descent optimization. Lower values (0.001) give more stable but slower training. Higher values (0.1) train faster but may overshoot. Default (0.01) is a good starting point.",
"default": 0.01
},
"samples": {
"type": "integer",
"title": "The samples",
"description": "Number of posterior samples during training for Bayesian inference. Higher values improve uncertainty estimates but slow training. Default (2) balances speed and quality.",
"default": 2
},
"grad_clip": {
"type": "number",
"title": "The grad clip",
"description": "Maximum gradient magnitude to prevent exploding gradients. Lower values make training more stable but may slow convergence. Default (10) is suitable for most models.",
"default": 10
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "Job queue priority from 1-100. Higher values are processed first. Model training is typically lower priority (30) since it's longer-running.",
"default": 30
}
},
"type": "object",
"title": "ModelParams",
"description": "Training hyperparameters and job settings for model building.",
"examples": [
{
"epochs": 500,
"grad_clip": 10,
"learning_rate": 0.01,
"priority": 30,
"samples": 2
}
]
},
{
"type": "null"
}
],
"description": "The parameter for the model/models. Will use default values if it's empty.",
"default": {
"epochs": 500,
"learning_rate": 0.01,
"samples": 2,
"grad_clip": 10,
"priority": 30
}
},
"model_detail": {
"description": "Core model configuration: dataset reference, training/evaluation dates, modelling combination (filters), and metadata (name, note).",
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
},
"train_dates": {
"anyOf": [
{
"items": {
"type": "string",
"format": "date-time"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Train Dates",
"description": "List of train dates."
},
"eval_dates": {
"anyOf": [
{
"items": {
"type": "string",
"format": "date-time"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Eval Dates",
"description": "List of eval dates."
},
"activate": {
"type": "boolean",
"title": "Activate",
"description": "Activate the model/dataset as soon as it is done training.",
"default": false
},
"early_stopping": {
"anyOf": [
{
"properties": {
"patience": {
"type": "integer",
"minimum": 1,
"title": "Patience",
"description": "How many of the last epochs should be used.",
"default": 100
},
"absolute_tolerance": {
"type": "number",
"minimum": 0,
"title": "Absolute Tolerance",
"description": "The absolute tollerance to use to determine to stop",
"default": 0.1
},
"relative_tolerance": {
"type": "number",
"minimum": 0,
"title": "Relative Tolerance",
"description": "The relative tollerance to use to determine to stop",
"default": 0.1
}
},
"type": "object",
"title": "EarlyStopping",
"description": "Config for early stopping."
},
{
"type": "null"
}
],
"description": "Early stopping configuration for the model training."
},
"modelling_combination": {
"description": "Modelling combination for the model.",
"properties": {
"country_code": {
"type": "string",
"title": "Country Code"
},
"region_code": {
"type": "string",
"title": "Region Code"
},
"grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"country_code",
"region_code",
"grouping"
],
"title": "ModellingCombinationBaseModel"
}
},
"type": "object",
"required": [
"modelling_combination"
],
"title": "ModelDetail"
},
"graph_detail": {
"anyOf": [
{
"properties": {
"graph": {
"anyOf": [
{
"properties": {
"nodes": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Nodes"
},
"edges": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Edges"
}
},
"type": "object",
"required": [
"nodes",
"edges"
],
"title": "Graph",
"description": "Schema for graph componens."
},
{
"type": "null"
}
],
"description": "Graph to build model for. The graph consists of nodes and edge, ex. {'nodes':[{'type':'Node.Data','id':'macro','key':'File:Macro|Indicator:CCI'},{'type':'Node.GraphGenerator.KPI','id':'sales', 'key':'File:Sales|Product:Health|Metric:UnitsSold'}],'edges':[{'arguments':['neutral'],'source':'macro','target':'sales'}]}"
},
"graph_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Graph Id",
"description": "The id of graph to use to create models."
},
"graph_variables": {
"anyOf": [
{
"properties": {
"targets": {
"anyOf": [
{
"properties": {
"targets": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Targets",
"description": "The targets to model."
},
"revenue_nodes": {
"type": "boolean",
"title": "Revenue Nodes",
"description": "For sales KPI's add individual revenue nodes aswell as\"\n \" a total revenue node, these nodes will be possible to see in \"\n \"the dashboards etc.",
"default": false
},
"profit_nodes": {
"type": "boolean",
"title": "Profit Nodes",
"description": "For sales KPI's add individual profit nodes aswell as\"\n \" a total profit node, these nodes will be possible to see in the \"\n \"dashboards etc.",
"default": false
}
},
"type": "object",
"title": "Target",
"description": "Config for controlling the targets."
},
{
"type": "null"
}
],
"default": {
"targets": [],
"revenue_nodes": false,
"profit_nodes": false
}
},
"trend": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
}
},
"type": "object",
"title": "Trend",
"description": "Controll the impact of sales."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
}
}
},
"season": {
"anyOf": [
{
"properties": {
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"shared": {
"type": "boolean",
"title": "Shared",
"description": "Should the effect be shared betwwen the targets or should the effect be individual per targets.",
"default": false
},
"multiplicative": {
"type": "boolean",
"title": "Multiplicative",
"description": "Use a multiplicative season.",
"default": false
}
},
"type": "object",
"title": "Season",
"description": "Controll the season."
},
{
"type": "null"
}
],
"default": {
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"shared": false,
"multiplicative": false
}
},
"holidays": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"shared": {
"type": "boolean",
"title": "Shared",
"description": "Should the effect be shared betwwen the targets or should the effect be individual per targets.",
"default": false
}
},
"type": "object",
"title": "Holidays",
"description": "Controll the impact of sales."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"shared": false
}
},
"media": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"net_profit_node": {
"type": "boolean",
"title": "Net Profit Node",
"description": "Construct a `NetProfit` node i.e. Profit-investments. This will be shown in the dashboards etc. as a `Response`",
"default": false
}
},
"type": "object",
"title": "Media",
"description": "Controll the media."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"effect_in_days": 120,
"variables": [],
"match_product": false,
"net_profit_node": false
}
},
"customer_experience": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"net_profit_node": {
"type": "boolean",
"title": "Net Profit Node",
"description": "Construct a `NetProfit` node i.e. Profit-investments. This will be shown in the dashboards etc. as a `Response`",
"default": false
}
},
"type": "object",
"title": "CustomerExperience",
"description": "Controll the customer expereince."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"effect_in_days": 120,
"variables": [],
"match_product": false,
"net_profit_node": false
}
},
"price": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Price",
"description": "Controll the price."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"match_product": false,
"variables": []
}
},
"distribution": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Distribution",
"description": "Controll the distribution."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"match_product": false,
"variables": []
}
},
"brand": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Brand",
"description": "Controll the brand."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"events": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Events",
"description": "Controll the events."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"macro": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Macro",
"description": "Controll the macro variables."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"visits": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Visits",
"description": "Controll the visits variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"weather": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Weather",
"description": "Controll the visits variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"variables": []
}
},
"extra": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Extra",
"description": "Controll the extra variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"variables": []
}
},
"competitor_price": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorPrice",
"description": "Controll the competitor price variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"variables": [],
"match_product": false
}
},
"competitor_media": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorMedia",
"description": "Controll the competitor media variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"effect_in_days": 120,
"variables": [],
"match_product": false
}
},
"competitor_brand": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "CompetitorBrand",
"description": "Controll the competitor media variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"variables": []
}
},
"competitor_distribution": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorDistribution",
"description": "Controll the competitor distribution variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"variables": [],
"match_product": false
}
}
},
"type": "object",
"title": "BasicModelVariables",
"description": "Variables config for the basic model."
},
{
"type": "null"
}
],
"description": "High-level effect information to use when auto-creating basic models."
}
},
"type": "object",
"title": "GraphDetail",
"description": "schema class of graph detail. graph, graph id, and graph variables."
},
{
"type": "null"
}
],
"description": "Graph structure defining variable relationships. Provide either a graph object directly, a graph_id to reference an existing graph, or graph_variables for auto-generation."
},
"add_prediction": {
"type": "boolean",
"title": "Add Prediction",
"description": "If True, automatically creates a full prediction job after model completes training. Useful for immediate model validation.",
"default": false
},
"add_priorposterior": {
"anyOf": [
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"samples": {
"type": "integer",
"title": "Samples",
"default": 100
},
"epochs": {
"type": "integer",
"title": "Epochs",
"default": 200
},
"sub_samples": {
"type": "integer",
"title": "Sub Samples",
"default": 3
},
"lr": {
"type": "number",
"title": "Lr",
"default": 0.01
},
"grad_clip": {
"type": "number",
"title": "The grad clip",
"description": "The value the gradient will be clipped during training to prevent exploding gradients.",
"default": 3
},
"baseline": {
"anyOf": [
{
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable",
"description": "Variable slug."
},
"baseline": {
"type": "number",
"title": "Baseline",
"description": "Set baseline."
}
},
"type": "object",
"required": [
"variable",
"baseline"
],
"title": "ReferencePointBaseline",
"description": "Attribution job baseline."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Baseline"
},
"referece_point_fallback": {
"anyOf": [
{
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback",
"description": "Attribution's reference point fallback."
},
{
"type": "null"
}
],
"description": "Reference point fallback.",
"default": "Zero"
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
}
},
"type": "object",
"title": "PriorPosterior",
"description": "Prior posterior request."
},
{
"type": "null"
}
],
"description": "If provided, automatically runs prior/posterior analysis after model completes. Compares learned parameters against prior distributions."
},
"add_attribution": {
"anyOf": [
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"samples": {
"type": "integer",
"title": "The samples",
"description": "Hom many subsamples to draw from the posterior distribution. The higher number of samples the better the uncertainty estimation becomes but it also takes longer to run.",
"default": 20
},
"baseline": {
"anyOf": [
{
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable",
"description": "Variable slug."
},
"baseline": {
"type": "number",
"title": "Baseline",
"description": "Set baseline."
}
},
"type": "object",
"required": [
"variable",
"baseline"
],
"title": "ReferencePointBaseline",
"description": "Attribution job baseline."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Baseline"
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
},
"quantiles": {
"anyOf": [
{
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Quantiles",
"default": [
1,
25,
50,
75,
99
]
},
"referece_point_fallback": {
"anyOf": [
{
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback",
"description": "Attribution's reference point fallback."
},
{
"type": "null"
}
],
"description": "Reference point fallback.",
"default": "Min"
},
"predicted_targets_as_data": {
"type": "boolean",
"title": "Predicted Targets As Data",
"description": "Set predicted targets as data.",
"default": true
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Optional integer seed. If omitted, the chained attribution inherits the parent job's seed."
},
"attribution_set": {
"anyOf": [
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"attributionjob_ids": {
"anyOf": [
{
"items": {
"anyOf": [
{
"type": "integer"
},
{
"properties": {
"attribution_id": {
"type": "integer",
"title": "Attribution Id",
"description": "The id of the attribution job."
},
"order": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Order",
"description": "Priority order for overlapping results (lower = higher priority). Defaults to list position."
}
},
"type": "object",
"required": [
"attribution_id"
],
"title": "AttributionFilters",
"description": "Attribution filters for the attribution set."
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attributionjob Ids",
"description": "List of attribution job IDs (integers) or filter objects to include. Referenced jobs must be in COMPLETED status. Use filter objects to apply variable/date filters when merging."
},
"activate": {
"type": "boolean",
"title": "Activate",
"description": "Set to true to make this the active attribution set for the Effects Dashboard immediately after creation completes.",
"default": false
},
"attributionset_ids": {
"anyOf": [
{
"items": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "AttributionSetType",
"description": "Attribution set type."
},
{
"properties": {
"attributionset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "AttributionSetType",
"description": "Attribution set type."
}
],
"title": "Attributionset Id",
"description": "The id of the attribution set."
},
"order": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Order",
"description": "Priority order for overlapping results (lower = higher priority). Defaults to list position."
}
},
"type": "object",
"required": [
"attributionset_id"
],
"title": "AttributionSetFilters",
"description": "Attribution set filters for the attribution set."
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attributionset Ids",
"description": "List of existing attribution set IDs to merge into this set. Use 'active' to reference the currently active set, or filter objects to apply variable filters when merging."
}
},
"type": "object",
"title": "AttributionRequestNoValidation",
"description": "Attribution set request wihtout validation."
},
{
"type": "null"
}
],
"description": "Auto-run attribution set after attribution finished."
},
"fit_attribution": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Fit Attribution",
"description": "Set attribution as fit attribution of the model.",
"default": true
}
},
"type": "object",
"title": "ModelAttribution",
"description": "Model attribution request."
},
{
"type": "null"
}
],
"description": "Auto-runs attribution analysis after model completes. Quantifies variable contributions to the target KPI."
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Optional integer seed for reproducible model training. If omitted, the server generates a random seed."
}
},
"type": "object",
"required": [
"model_detail"
],
"title": "ModelBuildRequest",
"description": "Request body for building a single ML model.",
"examples": [
{
"add_attribution": {
"fit_attribution": true,
"name": "Fit Attribution",
"priority": 30,
"quantiles": [
1,
25,
50,
75,
99
],
"samples": 20
},
"add_prediction": true,
"add_priorposterior": {
"epochs": 200,
"grad_clip": 3,
"lr": 0.01,
"name": "Prior Posterior Analysis",
"priority": 30,
"samples": 100,
"sub_samples": 3
},
"graph_detail": {
"graph_id": 1
},
"model_detail": {
"activate": true,
"dataset_id": 1,
"early_stopping": {
"absolute_tolerance": 0.1,
"patience": 100,
"relative_tolerance": 0.1
},
"modelling_combination": {
"country_code": "USA",
"grouping": "all",
"region_code": "all"
},
"name": "USA National Marketing Mix Model",
"note": "Primary model for US market analysis"
},
"model_param": {
"epochs": 500,
"grad_clip": 10,
"learning_rate": 0.01,
"priority": 30,
"samples": 2
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active model for its market segment"
},
"Country": {
"type": "string",
"title": "Country",
"description": "Country code from modelling combination (e.g., 'USA', 'GBR')"
},
"Region": {
"type": "string",
"title": "Region",
"description": "Region code from modelling combination (e.g., 'all', 'northeast')"
},
"Grouping": {
"type": "string",
"title": "Grouping",
"description": "Grouping code from modelling combination (e.g., 'all', 'retail')"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Model training completion timestamp"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Selected",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "Models",
"description": "Response schema for trained models listing and summary views.",
"examples": [
{
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Grouping": "all",
"IId": 1,
"JobId": 123,
"Name": "USA All Model",
"Note": "Model for USA market",
"Region": "all",
"Selected": true,
"Status": "completed"
}
]
}
}
}
},
"400": {
"description": "Invalid model build request: invalid graph, missing variables, conflicting dates, or invalid hyperparameters",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Project is in read-only state",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Build Multiple Models (/api/models/build_multiple_models_projects__team_id___project_id__build_model_multiple_post)
Train multiple ML models for different market segments in batch.
Efficient batch training for scenarios requiring models across multiple
modelling combinations (country/region/grouping). All models share the
same graph structure and training parameters but are trained independently
on their respective data segments.
Use Cases:
- Train models for multiple countries simultaneously
- Create region-specific models with consistent methodology
- Build product-line specific models in parallel
Response:
List of created model objects. Use GET /models/{model_id} to check status.
Notes:
- Models train in parallel for efficiency
- Failure of one model does not affect others
- Use GET /models/{model_id} to check individual model status
Related:
- POST /build/model: Train a single model
- GET /models: List all models with filtering
## POST /api/projects/{team_id}/{project_id}/build/model_multiple
Build Multiple Models
Train multiple ML models for different market segments in batch.
Efficient batch training for scenarios requiring models across multiple
modelling combinations (country/region/grouping). All models share the
same graph structure and training parameters but are trained independently
on their respective data segments.
Use Cases:
- Train models for multiple countries simultaneously
- Create region-specific models with consistent methodology
- Build product-line specific models in parallel
Response:
List of created model objects. Use GET /models/{model_id} to check status.
Notes:
- Models train in parallel for efficiency
- Failure of one model does not affect others
- Use GET /models/{model_id} to check individual model status
Related:
- POST /build/model: Train a single model
- GET /models: List all models with filtering
```json
{
"tags": [
"Models"
],
"summary": "Build Multiple Models",
"description": "Train multiple ML models for different market segments in batch.\n\nEfficient batch training for scenarios requiring models across multiple\nmodelling combinations (country/region/grouping). All models share the\nsame graph structure and training parameters but are trained independently\non their respective data segments.\n\nUse Cases:\n - Train models for multiple countries simultaneously\n - Create region-specific models with consistent methodology\n - Build product-line specific models in parallel\n\nResponse:\n List of created model objects. Use GET /models/{model_id} to check status.\n\nNotes:\n - Models train in parallel for efficiency\n - Failure of one model does not affect others\n - Use GET /models/{model_id} to check individual model status\n\nRelated:\n - POST /build/model: Train a single model\n - GET /models: List all models with filtering",
"operationId": "build_multiple_models_projects__team_id___project_id__build_model_multiple_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"model_param": {
"anyOf": [
{
"properties": {
"epochs": {
"type": "integer",
"title": "The epochs",
"description": "Maximum training iterations. Model may stop earlier if early_stopping is configured. Higher values allow more learning but risk overfitting. Default (500) works for most models.",
"default": 500
},
"learning_rate": {
"type": "number",
"title": "The learning rate",
"description": "Step size for gradient descent optimization. Lower values (0.001) give more stable but slower training. Higher values (0.1) train faster but may overshoot. Default (0.01) is a good starting point.",
"default": 0.01
},
"samples": {
"type": "integer",
"title": "The samples",
"description": "Number of posterior samples during training for Bayesian inference. Higher values improve uncertainty estimates but slow training. Default (2) balances speed and quality.",
"default": 2
},
"grad_clip": {
"type": "number",
"title": "The grad clip",
"description": "Maximum gradient magnitude to prevent exploding gradients. Lower values make training more stable but may slow convergence. Default (10) is suitable for most models.",
"default": 10
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "Job queue priority from 1-100. Higher values are processed first. Model training is typically lower priority (30) since it's longer-running.",
"default": 30
}
},
"type": "object",
"title": "ModelParams",
"description": "Training hyperparameters and job settings for model building.",
"examples": [
{
"epochs": 500,
"grad_clip": 10,
"learning_rate": 0.01,
"priority": 30,
"samples": 2
}
]
},
{
"type": "null"
}
],
"description": "The parameter for the model/models. Will use default values if it's empty.",
"default": {
"epochs": 500,
"learning_rate": 0.01,
"samples": 2,
"grad_clip": 10,
"priority": 30
}
},
"models_detail": {
"description": "Configuration for all models in the batch: dataset, training dates, and per-model settings (names, notes, modelling combinations). Each combination creates one model.",
"properties": {
"names": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Names",
"description": "Name list for the model, the list needs to be the same length with modelling_combinations."
},
"notes": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Notes",
"description": "Description for the model/dataset"
},
"prefixes": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Prefixes",
"description": "Prefix for the name."
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
},
"train_dates": {
"anyOf": [
{
"items": {
"type": "string",
"format": "date-time"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Train Dates",
"description": "List of train dates."
},
"eval_dates": {
"anyOf": [
{
"items": {
"type": "string",
"format": "date-time"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Eval Dates",
"description": "List of eval dates."
},
"activate": {
"type": "boolean",
"title": "Activate",
"description": "Activate the model/dataset as soon as it is done training.",
"default": false
},
"early_stopping": {
"anyOf": [
{
"properties": {
"patience": {
"type": "integer",
"minimum": 1,
"title": "Patience",
"description": "How many of the last epochs should be used.",
"default": 100
},
"absolute_tolerance": {
"type": "number",
"minimum": 0,
"title": "Absolute Tolerance",
"description": "The absolute tollerance to use to determine to stop",
"default": 0.1
},
"relative_tolerance": {
"type": "number",
"minimum": 0,
"title": "Relative Tolerance",
"description": "The relative tollerance to use to determine to stop",
"default": 0.1
}
},
"type": "object",
"title": "EarlyStopping",
"description": "Config for early stopping."
},
{
"type": "null"
}
],
"description": "Early stopping configuration for the model training."
},
"modelling_combinations": {
"items": {
"properties": {
"country_code": {
"type": "string",
"title": "Country Code"
},
"region_code": {
"type": "string",
"title": "Region Code"
},
"grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"country_code",
"region_code",
"grouping"
],
"title": "ModellingCombinationBaseModel",
"description": "Schema for getting modelling combination (BaseModel)."
},
"type": "array",
"title": "Modelling Combinations",
"description": "Modelling combination list for the models."
}
},
"type": "object",
"required": [
"modelling_combinations"
],
"title": "ModelsDetail"
},
"graphs_detail": {
"anyOf": [
{
"properties": {
"graphs": {
"anyOf": [
{
"items": {
"properties": {
"nodes": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Nodes"
},
"edges": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Edges"
}
},
"type": "object",
"required": [
"nodes",
"edges"
],
"title": "Graph",
"description": "Schema for graph componens."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Graphs",
"description": "List of graphs to build models for. Each graph consists of nodes and edge, ex. {'nodes':[{'type':'Node.Data','id':'macro','key':'File:Macro|Indicator:CCI'},{'type':'Node.GraphGenerator.KPI','id':'sales', 'key':'File:Sales|Product:Health|Metric:UnitsSold'}],'edges':[{'arguments':['neutral'],'source':'macro','target':'sales'}]}"
},
"graph_ids": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Graph Ids",
"description": "List of ids of graphs to use to create models."
},
"graph_variables": {
"anyOf": [
{
"properties": {
"targets": {
"anyOf": [
{
"properties": {
"targets": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Targets",
"description": "The targets to model."
},
"revenue_nodes": {
"type": "boolean",
"title": "Revenue Nodes",
"description": "For sales KPI's add individual revenue nodes aswell as\"\n \" a total revenue node, these nodes will be possible to see in \"\n \"the dashboards etc.",
"default": false
},
"profit_nodes": {
"type": "boolean",
"title": "Profit Nodes",
"description": "For sales KPI's add individual profit nodes aswell as\"\n \" a total profit node, these nodes will be possible to see in the \"\n \"dashboards etc.",
"default": false
}
},
"type": "object",
"title": "Target",
"description": "Config for controlling the targets."
},
{
"type": "null"
}
],
"default": {
"targets": [],
"revenue_nodes": false,
"profit_nodes": false
}
},
"trend": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
}
},
"type": "object",
"title": "Trend",
"description": "Controll the impact of sales."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
}
}
},
"season": {
"anyOf": [
{
"properties": {
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"shared": {
"type": "boolean",
"title": "Shared",
"description": "Should the effect be shared betwwen the targets or should the effect be individual per targets.",
"default": false
},
"multiplicative": {
"type": "boolean",
"title": "Multiplicative",
"description": "Use a multiplicative season.",
"default": false
}
},
"type": "object",
"title": "Season",
"description": "Controll the season."
},
{
"type": "null"
}
],
"default": {
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"shared": false,
"multiplicative": false
}
},
"holidays": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"shared": {
"type": "boolean",
"title": "Shared",
"description": "Should the effect be shared betwwen the targets or should the effect be individual per targets.",
"default": false
}
},
"type": "object",
"title": "Holidays",
"description": "Controll the impact of sales."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"shared": false
}
},
"media": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"net_profit_node": {
"type": "boolean",
"title": "Net Profit Node",
"description": "Construct a `NetProfit` node i.e. Profit-investments. This will be shown in the dashboards etc. as a `Response`",
"default": false
}
},
"type": "object",
"title": "Media",
"description": "Controll the media."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"effect_in_days": 120,
"variables": [],
"match_product": false,
"net_profit_node": false
}
},
"customer_experience": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"net_profit_node": {
"type": "boolean",
"title": "Net Profit Node",
"description": "Construct a `NetProfit` node i.e. Profit-investments. This will be shown in the dashboards etc. as a `Response`",
"default": false
}
},
"type": "object",
"title": "CustomerExperience",
"description": "Controll the customer expereince."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"effect_in_days": 120,
"variables": [],
"match_product": false,
"net_profit_node": false
}
},
"price": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Price",
"description": "Controll the price."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"match_product": false,
"variables": []
}
},
"distribution": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Distribution",
"description": "Controll the distribution."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"match_product": false,
"variables": []
}
},
"brand": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Brand",
"description": "Controll the brand."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"events": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Events",
"description": "Controll the events."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"macro": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Macro",
"description": "Controll the macro variables."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"visits": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Visits",
"description": "Controll the visits variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"weather": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Weather",
"description": "Controll the visits variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"variables": []
}
},
"extra": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Extra",
"description": "Controll the extra variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"variables": []
}
},
"competitor_price": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorPrice",
"description": "Controll the competitor price variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"variables": [],
"match_product": false
}
},
"competitor_media": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorMedia",
"description": "Controll the competitor media variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"effect_in_days": 120,
"variables": [],
"match_product": false
}
},
"competitor_brand": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "CompetitorBrand",
"description": "Controll the competitor media variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"variables": []
}
},
"competitor_distribution": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorDistribution",
"description": "Controll the competitor distribution variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"variables": [],
"match_product": false
}
}
},
"type": "object",
"title": "BasicModelVariables",
"description": "Variables config for the basic model."
},
{
"type": "null"
}
],
"description": "High-level effect information to use when auto-creating basic models."
}
},
"type": "object",
"title": "GraphsDetail",
"description": "schema class of graphs detail. graphs, graph ids, and graph variables."
},
{
"type": "null"
}
],
"description": "Graph structure(s) defining variable relationships. Provide either graph objects directly, graph IDs to reference existing graphs, or graph_variables for auto-generation."
},
"add_prediction": {
"type": "boolean",
"title": "Add Prediction",
"description": "If True, automatically creates a full prediction job after each model completes training. Useful for immediate model validation.",
"default": false
},
"add_priorposterior": {
"anyOf": [
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"samples": {
"type": "integer",
"title": "Samples",
"default": 100
},
"epochs": {
"type": "integer",
"title": "Epochs",
"default": 200
},
"sub_samples": {
"type": "integer",
"title": "Sub Samples",
"default": 3
},
"lr": {
"type": "number",
"title": "Lr",
"default": 0.01
},
"grad_clip": {
"type": "number",
"title": "The grad clip",
"description": "The value the gradient will be clipped during training to prevent exploding gradients.",
"default": 3
},
"baseline": {
"anyOf": [
{
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable",
"description": "Variable slug."
},
"baseline": {
"type": "number",
"title": "Baseline",
"description": "Set baseline."
}
},
"type": "object",
"required": [
"variable",
"baseline"
],
"title": "ReferencePointBaseline",
"description": "Attribution job baseline."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Baseline"
},
"referece_point_fallback": {
"anyOf": [
{
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback",
"description": "Attribution's reference point fallback."
},
{
"type": "null"
}
],
"description": "Reference point fallback.",
"default": "Zero"
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
}
},
"type": "object",
"title": "PriorPosterior",
"description": "Prior posterior request."
},
{
"type": "null"
}
],
"description": "If provided, automatically runs prior/posterior analysis after model completes. Compares learned parameters against prior distributions."
},
"add_attribution": {
"anyOf": [
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"samples": {
"type": "integer",
"title": "The samples",
"description": "Hom many subsamples to draw from the posterior distribution. The higher number of samples the better the uncertainty estimation becomes but it also takes longer to run.",
"default": 20
},
"baseline": {
"anyOf": [
{
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable",
"description": "Variable slug."
},
"baseline": {
"type": "number",
"title": "Baseline",
"description": "Set baseline."
}
},
"type": "object",
"required": [
"variable",
"baseline"
],
"title": "ReferencePointBaseline",
"description": "Attribution job baseline."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Baseline"
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
},
"quantiles": {
"anyOf": [
{
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Quantiles",
"default": [
1,
25,
50,
75,
99
]
},
"referece_point_fallback": {
"anyOf": [
{
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback",
"description": "Attribution's reference point fallback."
},
{
"type": "null"
}
],
"description": "Reference point fallback.",
"default": "Min"
},
"predicted_targets_as_data": {
"type": "boolean",
"title": "Predicted Targets As Data",
"description": "Set predicted targets as data.",
"default": true
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Optional integer seed. If omitted, the chained attribution inherits the parent job's seed."
},
"attribution_set": {
"anyOf": [
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"attributionjob_ids": {
"anyOf": [
{
"items": {
"anyOf": [
{
"type": "integer"
},
{
"properties": {
"attribution_id": {
"type": "integer",
"title": "Attribution Id",
"description": "The id of the attribution job."
},
"order": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Order",
"description": "Priority order for overlapping results (lower = higher priority). Defaults to list position."
}
},
"type": "object",
"required": [
"attribution_id"
],
"title": "AttributionFilters",
"description": "Attribution filters for the attribution set."
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attributionjob Ids",
"description": "List of attribution job IDs (integers) or filter objects to include. Referenced jobs must be in COMPLETED status. Use filter objects to apply variable/date filters when merging."
},
"activate": {
"type": "boolean",
"title": "Activate",
"description": "Set to true to make this the active attribution set for the Effects Dashboard immediately after creation completes.",
"default": false
},
"attributionset_ids": {
"anyOf": [
{
"items": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "AttributionSetType",
"description": "Attribution set type."
},
{
"properties": {
"attributionset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "AttributionSetType",
"description": "Attribution set type."
}
],
"title": "Attributionset Id",
"description": "The id of the attribution set."
},
"order": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Order",
"description": "Priority order for overlapping results (lower = higher priority). Defaults to list position."
}
},
"type": "object",
"required": [
"attributionset_id"
],
"title": "AttributionSetFilters",
"description": "Attribution set filters for the attribution set."
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attributionset Ids",
"description": "List of existing attribution set IDs to merge into this set. Use 'active' to reference the currently active set, or filter objects to apply variable filters when merging."
}
},
"type": "object",
"title": "AttributionRequestNoValidation",
"description": "Attribution set request wihtout validation."
},
{
"type": "null"
}
],
"description": "Auto-run attribution set after attribution finished."
},
"fit_attribution": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Fit Attribution",
"description": "Set attribution as fit attribution of the model.",
"default": true
}
},
"type": "object",
"title": "ModelAttribution",
"description": "Model attribution request."
},
{
"type": "null"
}
],
"description": "Auto-runs attribution analysis after model completes. Quantifies variable contributions to the target KPI."
},
"allow_no_sales": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Allow No Sales",
"description": "Allow submission without required dataset types (e.g., Sales). Set to True for models that don't require outcome data.",
"default": false
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Optional integer seed for reproducible model training. If omitted, the server generates a random seed shared across all models in the batch."
}
},
"type": "object",
"required": [
"models_detail"
],
"title": "ModelBuildMultipleRequest",
"description": "Request body for building multiple models in a single batch job.",
"examples": [
{
"add_attribution": {
"fit_attribution": true,
"name": "Auto Attribution",
"priority": 30,
"quantiles": [
1,
25,
50,
75,
99
],
"samples": 20
},
"add_prediction": true,
"allow_no_sales": false,
"graphs_detail": {
"graph_ids": [
1
]
},
"model_param": {
"epochs": 500,
"grad_clip": 10,
"learning_rate": 0.01,
"priority": 30,
"samples": 2
},
"models_detail": {
"activate": true,
"dataset_id": 1,
"early_stopping": {
"absolute_tolerance": 0.1,
"patience": 100,
"relative_tolerance": 0.1
},
"modelling_combinations": [
{
"country_code": "USA",
"grouping": "all",
"region_code": "all"
},
{
"country_code": "GBR",
"grouping": "all",
"region_code": "all"
}
],
"names": [
"USA National Model",
"GBR National Model"
],
"notes": [
"USA market model",
"GBR market model"
]
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active model for its market segment"
},
"Country": {
"type": "string",
"title": "Country",
"description": "Country code from modelling combination (e.g., 'USA', 'GBR')"
},
"Region": {
"type": "string",
"title": "Region",
"description": "Region code from modelling combination (e.g., 'all', 'northeast')"
},
"Grouping": {
"type": "string",
"title": "Grouping",
"description": "Grouping code from modelling combination (e.g., 'all', 'retail')"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Model training completion timestamp"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Selected",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "Models",
"description": "Response schema for trained models listing and summary views.",
"examples": [
{
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Grouping": "all",
"IId": 1,
"JobId": 123,
"Name": "USA All Model",
"Note": "Model for USA market",
"Region": "all",
"Selected": true,
"Status": "completed"
}
]
},
"title": "Response Build Multiple Models Projects Team Id Project Id Build Model Multiple Post"
}
}
}
},
"400": {
"description": "Invalid model build request: invalid graph, missing variables, conflicting dates, or invalid hyperparameters",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Project is in read-only state",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Basic Graph (/api/models/get_basic_graph_projects__team_id___project_id__build_graph_basic_post)
Get default graph.
This endpoint generates a basic graph based on the provided request data, project,
and session.
## POST /api/projects/{team_id}/{project_id}/build/graph_basic
Get Basic Graph
Get default graph.
This endpoint generates a basic graph based on the provided request data, project,
and session.
```json
{
"tags": [
"Models"
],
"summary": "Get Basic Graph",
"description": "Get default graph.\n\nThis endpoint generates a basic graph based on the provided request data, project,\nand session.",
"operationId": "get_basic_graph_projects__team_id___project_id__build_graph_basic_post",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"modelling_combination": {
"description": "Modelling combination for the model.",
"properties": {
"country_code": {
"type": "string",
"title": "Country Code"
},
"region_code": {
"type": "string",
"title": "Region Code"
},
"grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"country_code",
"region_code",
"grouping"
],
"title": "ModellingCombinationBaseModel"
},
"graph_variables": {
"anyOf": [
{
"properties": {
"targets": {
"anyOf": [
{
"properties": {
"targets": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Targets",
"description": "The targets to model."
},
"revenue_nodes": {
"type": "boolean",
"title": "Revenue Nodes",
"description": "For sales KPI's add individual revenue nodes aswell as\"\n \" a total revenue node, these nodes will be possible to see in \"\n \"the dashboards etc.",
"default": false
},
"profit_nodes": {
"type": "boolean",
"title": "Profit Nodes",
"description": "For sales KPI's add individual profit nodes aswell as\"\n \" a total profit node, these nodes will be possible to see in the \"\n \"dashboards etc.",
"default": false
}
},
"type": "object",
"title": "Target",
"description": "Config for controlling the targets."
},
{
"type": "null"
}
],
"default": {
"targets": [],
"revenue_nodes": false,
"profit_nodes": false
}
},
"trend": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
}
},
"type": "object",
"title": "Trend",
"description": "Controll the impact of sales."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
}
}
},
"season": {
"anyOf": [
{
"properties": {
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"shared": {
"type": "boolean",
"title": "Shared",
"description": "Should the effect be shared betwwen the targets or should the effect be individual per targets.",
"default": false
},
"multiplicative": {
"type": "boolean",
"title": "Multiplicative",
"description": "Use a multiplicative season.",
"default": false
}
},
"type": "object",
"title": "Season",
"description": "Controll the season."
},
{
"type": "null"
}
],
"default": {
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"shared": false,
"multiplicative": false
}
},
"holidays": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"shared": {
"type": "boolean",
"title": "Shared",
"description": "Should the effect be shared betwwen the targets or should the effect be individual per targets.",
"default": false
}
},
"type": "object",
"title": "Holidays",
"description": "Controll the impact of sales."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"shared": false
}
},
"media": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"net_profit_node": {
"type": "boolean",
"title": "Net Profit Node",
"description": "Construct a `NetProfit` node i.e. Profit-investments. This will be shown in the dashboards etc. as a `Response`",
"default": false
}
},
"type": "object",
"title": "Media",
"description": "Controll the media."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"effect_in_days": 120,
"variables": [],
"match_product": false,
"net_profit_node": false
}
},
"customer_experience": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"net_profit_node": {
"type": "boolean",
"title": "Net Profit Node",
"description": "Construct a `NetProfit` node i.e. Profit-investments. This will be shown in the dashboards etc. as a `Response`",
"default": false
}
},
"type": "object",
"title": "CustomerExperience",
"description": "Controll the customer expereince."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"effect_in_days": 120,
"variables": [],
"match_product": false,
"net_profit_node": false
}
},
"price": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Price",
"description": "Controll the price."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"match_product": false,
"variables": []
}
},
"distribution": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Distribution",
"description": "Controll the distribution."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"match_product": false,
"variables": []
}
},
"brand": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Brand",
"description": "Controll the brand."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"events": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Events",
"description": "Controll the events."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"macro": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Macro",
"description": "Controll the macro variables."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"visits": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Visits",
"description": "Controll the visits variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"weather": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Weather",
"description": "Controll the visits variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"variables": []
}
},
"extra": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Extra",
"description": "Controll the extra variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"variables": []
}
},
"competitor_price": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorPrice",
"description": "Controll the competitor price variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"variables": [],
"match_product": false
}
},
"competitor_media": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorMedia",
"description": "Controll the competitor media variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"effect_in_days": 120,
"variables": [],
"match_product": false
}
},
"competitor_brand": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "CompetitorBrand",
"description": "Controll the competitor media variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"variables": []
}
},
"competitor_distribution": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorDistribution",
"description": "Controll the competitor distribution variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"variables": [],
"match_product": false
}
}
},
"type": "object",
"title": "BasicModelVariables",
"description": "Variables config for the basic model."
},
{
"type": "null"
}
],
"description": "High-level effect information to use when auto-creating basic models."
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
},
"dates": {
"anyOf": [
{
"items": {
"type": "string",
"format": "date-time"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Dates",
"description": "List of dates."
}
},
"type": "object",
"required": [
"modelling_combination"
],
"title": "BasicGraphRequest",
"description": "Schemas of basic graph request endpoint."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Basic Graph Tasks (/api/models/list_basic_graph_tasks_projects__team_id___project_id__build_graph_basic_job_get)
Get list of graph jobs.
This endpoint get list of graph basic job based on the provided
request data and project.
## GET /api/projects/{team_id}/{project_id}/build/graph_basic/job
List Basic Graph Tasks
Get list of graph jobs.
This endpoint get list of graph basic job based on the provided
request data and project.
```json
{
"tags": [
"Models"
],
"summary": "List Basic Graph Tasks",
"description": "Get list of graph jobs.\n\nThis endpoint get list of graph basic job based on the provided\nrequest data and project.",
"operationId": "list_basic_graph_tasks_projects__team_id___project_id__build_graph_basic_job_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"completed\"]]}'\n - By graph ID: filters='{\"Graph.Id\": [[\"=\", \"42\"]]}'\n - By model usage: filters='{\"Models.Name\": [[\"contains\", \"US_Model\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"completed\"]]}'\n - By graph ID: filters='{\"Graph.Id\": [[\"=\", \"42\"]]}'\n - By model usage: filters='{\"Models.Name\": [[\"contains\", \"US_Model\"]]}'\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier for the graph job"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
}
},
"type": "object",
"required": [
"IId",
"Status"
],
"title": "GraphsBasicJob",
"description": "Response schema for graph instantiation jobs."
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[GraphsBasicJob]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Submit Basic Graph Task (/api/models/submit_basic_graph_task_projects__team_id___project_id__build_graph_basic_job_post)
Get default graph.
This endpoint generates a basic graph based on the provided request data, project,
and session. This will be done as a job in the backgroud.
## POST /api/projects/{team_id}/{project_id}/build/graph_basic/job
Submit Basic Graph Task
Get default graph.
This endpoint generates a basic graph based on the provided request data, project,
and session. This will be done as a job in the backgroud.
```json
{
"tags": [
"Models"
],
"summary": "Submit Basic Graph Task",
"description": "Get default graph.\n\nThis endpoint generates a basic graph based on the provided request data, project,\nand session. This will be done as a job in the backgroud.",
"operationId": "submit_basic_graph_task_projects__team_id___project_id__build_graph_basic_job_post",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"modelling_combination": {
"description": "Modelling combination for the model.",
"properties": {
"country_code": {
"type": "string",
"title": "Country Code"
},
"region_code": {
"type": "string",
"title": "Region Code"
},
"grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"country_code",
"region_code",
"grouping"
],
"title": "ModellingCombinationBaseModel"
},
"graph_variables": {
"anyOf": [
{
"properties": {
"targets": {
"anyOf": [
{
"properties": {
"targets": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Targets",
"description": "The targets to model."
},
"revenue_nodes": {
"type": "boolean",
"title": "Revenue Nodes",
"description": "For sales KPI's add individual revenue nodes aswell as\"\n \" a total revenue node, these nodes will be possible to see in \"\n \"the dashboards etc.",
"default": false
},
"profit_nodes": {
"type": "boolean",
"title": "Profit Nodes",
"description": "For sales KPI's add individual profit nodes aswell as\"\n \" a total profit node, these nodes will be possible to see in the \"\n \"dashboards etc.",
"default": false
}
},
"type": "object",
"title": "Target",
"description": "Config for controlling the targets."
},
{
"type": "null"
}
],
"default": {
"targets": [],
"revenue_nodes": false,
"profit_nodes": false
}
},
"trend": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
}
},
"type": "object",
"title": "Trend",
"description": "Controll the impact of sales."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
}
}
},
"season": {
"anyOf": [
{
"properties": {
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"shared": {
"type": "boolean",
"title": "Shared",
"description": "Should the effect be shared betwwen the targets or should the effect be individual per targets.",
"default": false
},
"multiplicative": {
"type": "boolean",
"title": "Multiplicative",
"description": "Use a multiplicative season.",
"default": false
}
},
"type": "object",
"title": "Season",
"description": "Controll the season."
},
{
"type": "null"
}
],
"default": {
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"shared": false,
"multiplicative": false
}
},
"holidays": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"shared": {
"type": "boolean",
"title": "Shared",
"description": "Should the effect be shared betwwen the targets or should the effect be individual per targets.",
"default": false
}
},
"type": "object",
"title": "Holidays",
"description": "Controll the impact of sales."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"shared": false
}
},
"media": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"net_profit_node": {
"type": "boolean",
"title": "Net Profit Node",
"description": "Construct a `NetProfit` node i.e. Profit-investments. This will be shown in the dashboards etc. as a `Response`",
"default": false
}
},
"type": "object",
"title": "Media",
"description": "Controll the media."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"effect_in_days": 120,
"variables": [],
"match_product": false,
"net_profit_node": false
}
},
"customer_experience": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"net_profit_node": {
"type": "boolean",
"title": "Net Profit Node",
"description": "Construct a `NetProfit` node i.e. Profit-investments. This will be shown in the dashboards etc. as a `Response`",
"default": false
}
},
"type": "object",
"title": "CustomerExperience",
"description": "Controll the customer expereince."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"effect_in_days": 120,
"variables": [],
"match_product": false,
"net_profit_node": false
}
},
"price": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Price",
"description": "Controll the price."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"match_product": false,
"variables": []
}
},
"distribution": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Distribution",
"description": "Controll the distribution."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"match_product": false,
"variables": []
}
},
"brand": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Brand",
"description": "Controll the brand."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"events": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Events",
"description": "Controll the events."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"macro": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Macro",
"description": "Controll the macro variables."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"visits": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Visits",
"description": "Controll the visits variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"weather": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Weather",
"description": "Controll the visits variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"variables": []
}
},
"extra": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Extra",
"description": "Controll the extra variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"variables": []
}
},
"competitor_price": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorPrice",
"description": "Controll the competitor price variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"variables": [],
"match_product": false
}
},
"competitor_media": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorMedia",
"description": "Controll the competitor media variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"effect_in_days": 120,
"variables": [],
"match_product": false
}
},
"competitor_brand": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "CompetitorBrand",
"description": "Controll the competitor media variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"variables": []
}
},
"competitor_distribution": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorDistribution",
"description": "Controll the competitor distribution variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"variables": [],
"match_product": false
}
}
},
"type": "object",
"title": "BasicModelVariables",
"description": "Variables config for the basic model."
},
{
"type": "null"
}
],
"description": "High-level effect information to use when auto-creating basic models."
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
},
"dates": {
"anyOf": [
{
"items": {
"type": "string",
"format": "date-time"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Dates",
"description": "List of dates."
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
}
},
"type": "object",
"required": [
"modelling_combination"
],
"title": "BasicGraphJobRequest",
"description": "Schemas of basic graph job request endpoint."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier for the graph job"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
}
},
"type": "object",
"required": [
"IId",
"Status"
],
"title": "GraphsBasicJob",
"description": "Response schema for graph instantiation jobs."
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Graph Basic Task (/api/models/get_graph_basic_task_projects__team_id___project_id__build_graph_basic_job__job_id__get)
Get graph job result from capability via drun.
## GET /api/projects/{team_id}/{project_id}/build/graph_basic/job/{job_id}
Get Graph Basic Task
Get graph job result from capability via drun.
```json
{
"tags": [
"Models"
],
"summary": "Get Graph Basic Task",
"description": "Get graph job result from capability via drun.",
"operationId": "get_graph_basic_task_projects__team_id___project_id__build_graph_basic_job__job_id__get",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide graph basic job path.",
"title": "Job Id"
},
"description": "Provide graph basic job path."
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"Task": {
"anyOf": [
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"Topic": {
"type": "string",
"enum": [
"ATTRIBUTIONSET",
"ATTRIBUTIONJOB",
"SIMULATIONJOB",
"PREDICTIONJOB",
"TRAINJOB",
"DATASET",
"DATAUPLOAD",
"GRAPHCONSTRUCT",
"GENERAL",
"OPTIMIZATIONJOB",
"RESPOSNSECURVEJOB",
"PRIORPOSTERIORJOB",
"EXCELJOB",
"GRAPHBASIC",
"FEATUREIMPORTANCE",
"GRAPHSYNERGY"
],
"title": "TaskTopics",
"description": "Task topics."
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"Id",
"Config",
"Topic",
"Status"
],
"title": "Task",
"description": "Reference task."
},
{
"type": "null"
}
]
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier for the graph job"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Response": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Response",
"description": "Graph instantiation response data"
}
},
"type": "object",
"required": [
"IId",
"Status"
],
"title": "DetailedGraphJob",
"description": "Detailed response schema for graph instantiation jobs."
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Basic Graph Task (/api/models/delete_basic_graph_task_projects__team_id___project_id__build_graph_basic_job__job_id__delete)
Delete graph job.
## DELETE /api/projects/{team_id}/{project_id}/build/graph_basic/job/{job_id}
Delete Basic Graph Task
Delete graph job.
```json
{
"tags": [
"Models"
],
"summary": "Delete Basic Graph Task",
"description": "Delete graph job.",
"operationId": "delete_basic_graph_task_projects__team_id___project_id__build_graph_basic_job__job_id__delete",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide graph basic job path.",
"title": "Job Id"
},
"description": "Provide graph basic job path."
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Synergy Models Graph (/api/models/get_synergy_models_graph_projects__team_id___project_id__build_graph_synergy_models_post)
Get synergy models graph.
This endpoint generates a synergy models graph based on the provided request data,
project, and session.
## POST /api/projects/{team_id}/{project_id}/build/graph_synergy_models
Get Synergy Models Graph
Get synergy models graph.
This endpoint generates a synergy models graph based on the provided request data,
project, and session.
```json
{
"tags": [
"Models"
],
"summary": "Get Synergy Models Graph",
"description": "Get synergy models graph.\n\nThis endpoint generates a synergy models graph based on the provided request data,\nproject, and session.",
"operationId": "get_synergy_models_graph_projects__team_id___project_id__build_graph_synergy_models_post",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"modelling_combination": {
"description": "Modelling combination for the model.",
"properties": {
"country_code": {
"type": "string",
"title": "Country Code"
},
"region_code": {
"type": "string",
"title": "Region Code"
},
"grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"country_code",
"region_code",
"grouping"
],
"title": "ModellingCombinationBaseModel"
},
"graph_variables": {
"anyOf": [
{
"properties": {
"targets": {
"anyOf": [
{
"properties": {
"targets": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Targets",
"description": "The targets to model."
},
"revenue_nodes": {
"type": "boolean",
"title": "Revenue Nodes",
"description": "For sales KPI's add individual revenue nodes aswell as\"\n \" a total revenue node, these nodes will be possible to see in \"\n \"the dashboards etc.",
"default": false
},
"profit_nodes": {
"type": "boolean",
"title": "Profit Nodes",
"description": "For sales KPI's add individual profit nodes aswell as\"\n \" a total profit node, these nodes will be possible to see in the \"\n \"dashboards etc.",
"default": false
}
},
"type": "object",
"title": "Target",
"description": "Config for controlling the targets."
},
{
"type": "null"
}
],
"default": {
"targets": [],
"revenue_nodes": false,
"profit_nodes": false
}
},
"trend": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
}
},
"type": "object",
"title": "Trend",
"description": "Controll the impact of sales."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
}
}
},
"season": {
"anyOf": [
{
"properties": {
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"shared": {
"type": "boolean",
"title": "Shared",
"description": "Should the effect be shared betwwen the targets or should the effect be individual per targets.",
"default": false
},
"multiplicative": {
"type": "boolean",
"title": "Multiplicative",
"description": "Use a multiplicative season.",
"default": false
}
},
"type": "object",
"title": "Season",
"description": "Controll the season."
},
{
"type": "null"
}
],
"default": {
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"shared": false,
"multiplicative": false
}
},
"holidays": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"shared": {
"type": "boolean",
"title": "Shared",
"description": "Should the effect be shared betwwen the targets or should the effect be individual per targets.",
"default": false
}
},
"type": "object",
"title": "Holidays",
"description": "Controll the impact of sales."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"shared": false
}
},
"media": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"net_profit_node": {
"type": "boolean",
"title": "Net Profit Node",
"description": "Construct a `NetProfit` node i.e. Profit-investments. This will be shown in the dashboards etc. as a `Response`",
"default": false
}
},
"type": "object",
"title": "Media",
"description": "Controll the media."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"effect_in_days": 120,
"variables": [],
"match_product": false,
"net_profit_node": false
}
},
"customer_experience": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"net_profit_node": {
"type": "boolean",
"title": "Net Profit Node",
"description": "Construct a `NetProfit` node i.e. Profit-investments. This will be shown in the dashboards etc. as a `Response`",
"default": false
}
},
"type": "object",
"title": "CustomerExperience",
"description": "Controll the customer expereince."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"effect_in_days": 120,
"variables": [],
"match_product": false,
"net_profit_node": false
}
},
"price": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Price",
"description": "Controll the price."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"match_product": false,
"variables": []
}
},
"distribution": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Distribution",
"description": "Controll the distribution."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"match_product": false,
"variables": []
}
},
"brand": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Brand",
"description": "Controll the brand."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"events": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Events",
"description": "Controll the events."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"macro": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Macro",
"description": "Controll the macro variables."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"visits": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Visits",
"description": "Controll the visits variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"weather": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Weather",
"description": "Controll the visits variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"variables": []
}
},
"extra": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Extra",
"description": "Controll the extra variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"variables": []
}
},
"competitor_price": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorPrice",
"description": "Controll the competitor price variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"variables": [],
"match_product": false
}
},
"competitor_media": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorMedia",
"description": "Controll the competitor media variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"effect_in_days": 120,
"variables": [],
"match_product": false
}
},
"competitor_brand": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "CompetitorBrand",
"description": "Controll the competitor media variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"variables": []
}
},
"competitor_distribution": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorDistribution",
"description": "Controll the competitor distribution variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"variables": [],
"match_product": false
}
}
},
"type": "object",
"title": "BasicModelVariables",
"description": "Variables config for the basic model."
},
{
"type": "null"
}
],
"description": "High-level effect information to use when auto-creating basic models."
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
},
"dates": {
"anyOf": [
{
"items": {
"type": "string",
"format": "date-time"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Dates",
"description": "List of dates."
}
},
"type": "object",
"required": [
"modelling_combination"
],
"title": "BasicGraphRequest",
"description": "Schemas of basic graph request endpoint."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Synergy Graph Tasks (/api/models/list_synergy_graph_tasks_projects__team_id___project_id__build_graph_synergy_models_job_get)
Get list of synergy models graph jobs.
This endpoint gets a list of synergy graph jobs based on the provided
request data and project.
## GET /api/projects/{team_id}/{project_id}/build/graph_synergy_models/job
List Synergy Graph Tasks
Get list of synergy models graph jobs.
This endpoint gets a list of synergy graph jobs based on the provided
request data and project.
```json
{
"tags": [
"Models"
],
"summary": "List Synergy Graph Tasks",
"description": "Get list of synergy models graph jobs.\n\nThis endpoint gets a list of synergy graph jobs based on the provided\nrequest data and project.",
"operationId": "list_synergy_graph_tasks_projects__team_id___project_id__build_graph_synergy_models_job_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"completed\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"completed\"]]}'\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier for the graph job"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
}
},
"type": "object",
"required": [
"IId",
"Status"
],
"title": "GraphsBasicJob",
"description": "Response schema for graph instantiation jobs."
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[GraphsBasicJob]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Submit Synergy Graph Task (/api/models/submit_synergy_graph_task_projects__team_id___project_id__build_graph_synergy_models_job_post)
Submit synergy models graph job.
This endpoint generates a synergy models graph based on the provided request data,
project, and session. This will be done as a job in the background.
## POST /api/projects/{team_id}/{project_id}/build/graph_synergy_models/job
Submit Synergy Graph Task
Submit synergy models graph job.
This endpoint generates a synergy models graph based on the provided request data,
project, and session. This will be done as a job in the background.
```json
{
"tags": [
"Models"
],
"summary": "Submit Synergy Graph Task",
"description": "Submit synergy models graph job.\n\nThis endpoint generates a synergy models graph based on the provided request data,\nproject, and session. This will be done as a job in the background.",
"operationId": "submit_synergy_graph_task_projects__team_id___project_id__build_graph_synergy_models_job_post",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"modelling_combination": {
"description": "Modelling combination for the model.",
"properties": {
"country_code": {
"type": "string",
"title": "Country Code"
},
"region_code": {
"type": "string",
"title": "Region Code"
},
"grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"country_code",
"region_code",
"grouping"
],
"title": "ModellingCombinationBaseModel"
},
"graph_variables": {
"anyOf": [
{
"properties": {
"targets": {
"anyOf": [
{
"properties": {
"targets": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Targets",
"description": "The targets to model."
},
"revenue_nodes": {
"type": "boolean",
"title": "Revenue Nodes",
"description": "For sales KPI's add individual revenue nodes aswell as\"\n \" a total revenue node, these nodes will be possible to see in \"\n \"the dashboards etc.",
"default": false
},
"profit_nodes": {
"type": "boolean",
"title": "Profit Nodes",
"description": "For sales KPI's add individual profit nodes aswell as\"\n \" a total profit node, these nodes will be possible to see in the \"\n \"dashboards etc.",
"default": false
}
},
"type": "object",
"title": "Target",
"description": "Config for controlling the targets."
},
{
"type": "null"
}
],
"default": {
"targets": [],
"revenue_nodes": false,
"profit_nodes": false
}
},
"trend": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
}
},
"type": "object",
"title": "Trend",
"description": "Controll the impact of sales."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
}
}
},
"season": {
"anyOf": [
{
"properties": {
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"shared": {
"type": "boolean",
"title": "Shared",
"description": "Should the effect be shared betwwen the targets or should the effect be individual per targets.",
"default": false
},
"multiplicative": {
"type": "boolean",
"title": "Multiplicative",
"description": "Use a multiplicative season.",
"default": false
}
},
"type": "object",
"title": "Season",
"description": "Controll the season."
},
{
"type": "null"
}
],
"default": {
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"shared": false,
"multiplicative": false
}
},
"holidays": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"shared": {
"type": "boolean",
"title": "Shared",
"description": "Should the effect be shared betwwen the targets or should the effect be individual per targets.",
"default": false
}
},
"type": "object",
"title": "Holidays",
"description": "Controll the impact of sales."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"shared": false
}
},
"media": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"net_profit_node": {
"type": "boolean",
"title": "Net Profit Node",
"description": "Construct a `NetProfit` node i.e. Profit-investments. This will be shown in the dashboards etc. as a `Response`",
"default": false
}
},
"type": "object",
"title": "Media",
"description": "Controll the media."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"effect_in_days": 120,
"variables": [],
"match_product": false,
"net_profit_node": false
}
},
"customer_experience": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"net_profit_node": {
"type": "boolean",
"title": "Net Profit Node",
"description": "Construct a `NetProfit` node i.e. Profit-investments. This will be shown in the dashboards etc. as a `Response`",
"default": false
}
},
"type": "object",
"title": "CustomerExperience",
"description": "Controll the customer expereince."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"effect_in_days": 120,
"variables": [],
"match_product": false,
"net_profit_node": false
}
},
"price": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Price",
"description": "Controll the price."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"match_product": false,
"variables": []
}
},
"distribution": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Distribution",
"description": "Controll the distribution."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"match_product": false,
"variables": []
}
},
"brand": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Brand",
"description": "Controll the brand."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"events": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Events",
"description": "Controll the events."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"macro": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Macro",
"description": "Controll the macro variables."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"visits": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
],
"default": {
"mean": 0.1,
"std": 0.2
}
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Visits",
"description": "Controll the visits variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"effect": {
"mean": 0.1,
"std": 0.2,
"type": "Effect.ImpactSize"
},
"variables": []
}
},
"weather": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Weather",
"description": "Controll the visits variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"variables": []
}
},
"extra": {
"anyOf": [
{
"properties": {
"influence": {
"default": "neutral",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "Extra",
"description": "Controll the extra variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "neutral",
"variables": []
}
},
"competitor_price": {
"anyOf": [
{
"properties": {
"influence": {
"default": "positive",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorPrice",
"description": "Controll the competitor price variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "positive",
"variables": [],
"match_product": false
}
},
"competitor_media": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"effect_in_days": {
"type": "number",
"minimum": 1,
"title": "Effect In Days",
"description": "For how many days in to the future do we expect the a media Investmentto have an impact",
"default": 120
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorMedia",
"description": "Controll the competitor media variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"effect_in_days": 120,
"variables": [],
"match_product": false
}
},
"competitor_brand": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
}
},
"type": "object",
"title": "CompetitorBrand",
"description": "Controll the competitor media variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"variables": []
}
},
"competitor_distribution": {
"anyOf": [
{
"properties": {
"influence": {
"default": "negative",
"type": "string",
"enum": [
"positive",
"negative",
"neutral"
],
"title": "PosNegNeu",
"description": "Denote it is Positive, Negative or Neutral."
},
"effect": {
"anyOf": [
{
"properties": {
"mean": {
"type": "number",
"title": "Mean",
"description": "The mean impact of the variable",
"default": 0.1
},
"std": {
"type": "number",
"title": "Std",
"description": "Allowed Variation in the model",
"default": 0.2
}
},
"type": "object",
"title": "ImpactSize",
"description": "How big impact will the varible group have on sales."
},
{
"type": "null"
}
]
},
"variables": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Variables",
"description": "The subset of variables to include, if not set all variables will be used."
},
"match_product": {
"type": "boolean",
"title": "Match Product",
"description": "Match the product of the variable to the product in the kpi, if no match for the product the variable will be excluded.",
"default": false
}
},
"type": "object",
"title": "CompetitorDistribution",
"description": "Controll the competitor distribution variabels."
},
{
"type": "null"
}
],
"default": {
"influence": "negative",
"variables": [],
"match_product": false
}
}
},
"type": "object",
"title": "BasicModelVariables",
"description": "Variables config for the basic model."
},
{
"type": "null"
}
],
"description": "High-level effect information to use when auto-creating basic models."
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
},
"dates": {
"anyOf": [
{
"items": {
"type": "string",
"format": "date-time"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Dates",
"description": "List of dates."
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
}
},
"type": "object",
"required": [
"modelling_combination"
],
"title": "BasicGraphJobRequest",
"description": "Schemas of basic graph job request endpoint."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier for the graph job"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
}
},
"type": "object",
"required": [
"IId",
"Status"
],
"title": "GraphsBasicJob",
"description": "Response schema for graph instantiation jobs."
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Synergy Graph Task (/api/models/get_synergy_graph_task_projects__team_id___project_id__build_graph_synergy_models_job__job_id__get)
Get synergy models graph job result.
## GET /api/projects/{team_id}/{project_id}/build/graph_synergy_models/job/{job_id}
Get Synergy Graph Task
Get synergy models graph job result.
```json
{
"tags": [
"Models"
],
"summary": "Get Synergy Graph Task",
"description": "Get synergy models graph job result.",
"operationId": "get_synergy_graph_task_projects__team_id___project_id__build_graph_synergy_models_job__job_id__get",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide graph synergy job path.",
"title": "Job Id"
},
"description": "Provide graph synergy job path."
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"Task": {
"anyOf": [
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"Topic": {
"type": "string",
"enum": [
"ATTRIBUTIONSET",
"ATTRIBUTIONJOB",
"SIMULATIONJOB",
"PREDICTIONJOB",
"TRAINJOB",
"DATASET",
"DATAUPLOAD",
"GRAPHCONSTRUCT",
"GENERAL",
"OPTIMIZATIONJOB",
"RESPOSNSECURVEJOB",
"PRIORPOSTERIORJOB",
"EXCELJOB",
"GRAPHBASIC",
"FEATUREIMPORTANCE",
"GRAPHSYNERGY"
],
"title": "TaskTopics",
"description": "Task topics."
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"Id",
"Config",
"Topic",
"Status"
],
"title": "Task",
"description": "Reference task."
},
{
"type": "null"
}
]
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier for the graph job"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Response": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Response",
"description": "Graph instantiation response data"
}
},
"type": "object",
"required": [
"IId",
"Status"
],
"title": "DetailedGraphJob",
"description": "Detailed response schema for graph instantiation jobs."
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Synergy Graph Task (/api/models/delete_synergy_graph_task_projects__team_id___project_id__build_graph_synergy_models_job__job_id__delete)
Delete synergy models graph job.
## DELETE /api/projects/{team_id}/{project_id}/build/graph_synergy_models/job/{job_id}
Delete Synergy Graph Task
Delete synergy models graph job.
```json
{
"tags": [
"Models"
],
"summary": "Delete Synergy Graph Task",
"description": "Delete synergy models graph job.",
"operationId": "delete_synergy_graph_task_projects__team_id___project_id__build_graph_synergy_models_job__job_id__delete",
"parameters": [
{
"name": "job_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide graph synergy job path.",
"title": "Job Id"
},
"description": "Provide graph synergy job path."
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Models (/api/models/list_models_projects__team_id___project_id__models_get)
List all trained models in the project with optional filtering.
Returns a paginated list of models, useful for finding trained models
to use in predictions, simulations, or optimizations.
Query Parameters:
- filters: JSON filter expressions to narrow results
Example: '{"Status": [["=", "COMPLETED"]], "Country": [["=", "USA"]]}'
Response:
Paginated list of models.
Related:
- GET /models/{model_id}: Get full model details
- POST /build/model: Train a new model
- POST /models/{model_id}/activate: Set as active model
## GET /api/projects/{team_id}/{project_id}/models
List Models
List all trained models in the project with optional filtering.
Returns a paginated list of models, useful for finding trained models
to use in predictions, simulations, or optimizations.
Query Parameters:
- filters: JSON filter expressions to narrow results
Example: '{"Status": [["=", "COMPLETED"]], "Country": [["=", "USA"]]}'
Response:
Paginated list of models.
Related:
- GET /models/{model_id}: Get full model details
- POST /build/model: Train a new model
- POST /models/{model_id}/activate: Set as active model
```json
{
"tags": [
"Models"
],
"summary": "List Models",
"description": "List all trained models in the project with optional filtering.\n\nReturns a paginated list of models, useful for finding trained models\nto use in predictions, simulations, or optimizations.\n\nQuery Parameters:\n - filters: JSON filter expressions to narrow results\n Example: '{\"Status\": [[\"=\", \"COMPLETED\"]], \"Country\": [[\"=\", \"USA\"]]}'\n\nResponse:\n Paginated list of models.\n\nRelated:\n - GET /models/{model_id}: Get full model details\n - POST /build/model: Train a new model\n - POST /models/{model_id}/activate: Set as active model",
"operationId": "list_models_projects__team_id___project_id__models_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Multiple filters create OR logic.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By country: filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By name pattern: filters='{\"Name\": [[\"ilike\", \"%Q4%\"]]}'\n - By date: filters='{\"CreatedDate\": [[\">=\", \"2024-01-01\"]]}'\n - Active models only: filters='{\"Selected\": [[\"=\", \"true\"]]}'\n - By related dataset: filters='{\"DataSet.Name\": [[\"contains\", \"Marketing\"]]}'\n - Combined: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - Sort by date: filters='{\"CreatedDate\": [[\"orderby\", \"desc\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Multiple filters create OR logic.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By country: filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By name pattern: filters='{\"Name\": [[\"ilike\", \"%Q4%\"]]}'\n - By date: filters='{\"CreatedDate\": [[\">=\", \"2024-01-01\"]]}'\n - Active models only: filters='{\"Selected\": [[\"=\", \"true\"]]}'\n - By related dataset: filters='{\"DataSet.Name\": [[\"contains\", \"Marketing\"]]}'\n - Combined: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - Sort by date: filters='{\"CreatedDate\": [[\"orderby\", \"desc\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active model for its market segment"
},
"Country": {
"type": "string",
"title": "Country",
"description": "Country code from modelling combination (e.g., 'USA', 'GBR')"
},
"Region": {
"type": "string",
"title": "Region",
"description": "Region code from modelling combination (e.g., 'all', 'northeast')"
},
"Grouping": {
"type": "string",
"title": "Grouping",
"description": "Grouping code from modelling combination (e.g., 'all', 'retail')"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Model training completion timestamp"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Selected",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "Models",
"description": "Response schema for trained models listing and summary views.",
"examples": [
{
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Grouping": "all",
"IId": 1,
"JobId": 123,
"Name": "USA All Model",
"Note": "Model for USA market",
"Region": "all",
"Selected": true,
"Status": "completed"
}
]
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[Models]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Bulk Delete Models (/api/models/bulk_delete_models_projects__team_id___project_id__models_delete)
Bulk delete models matching the given filters.
Marks all matching models for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
Active models and models with active attribution sets are excluded.
## DELETE /api/projects/{team_id}/{project_id}/models
Bulk Delete Models
Bulk delete models matching the given filters.
Marks all matching models for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
Active models and models with active attribution sets are excluded.
```json
{
"tags": [
"Models"
],
"summary": "Bulk Delete Models",
"description": "Bulk delete models matching the given filters.\n\nMarks all matching models for deletion and publishes delete messages to\nRabbitMQ concurrently in the background via a single DB round-trip each.\nActive models and models with active attribution sets are excluded.",
"operationId": "bulk_delete_models_projects__team_id___project_id__models_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /models.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By country: filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - By date: filters='{\"CreatedDate\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /models.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By country: filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - By date: filters='{\"CreatedDate\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n "
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Model Active History (/api/models/list_model_active_history_projects__team_id___project_id__models_active_history_get)
List the history of active model changes for this project.
## GET /api/projects/{team_id}/{project_id}/models/active-history
List Model Active History
List the history of active model changes for this project.
```json
{
"tags": [
"Models"
],
"summary": "List Model Active History",
"description": "List the history of active model changes for this project.",
"operationId": "list_model_active_history_projects__team_id___project_id__models_active_history_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "JSON filter expressions. Filterable fields: UpdatedAt (>=, <=), UpdatedByUser (=, contains), ModelId (=, in), Country (=), Region (=), Grouping (=). Example: filters='{\"Country\": [[\"=\", \"SWE\"]]}'",
"title": "Filters"
},
"description": "JSON filter expressions. Filterable fields: UpdatedAt (>=, <=), UpdatedByUser (=, contains), ModelId (=, in), Country (=), Region (=), Grouping (=). Example: filters='{\"Country\": [[\"=\", \"SWE\"]]}'"
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"ModelId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Modelid"
},
"UpdatedByUser": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updatedbyuser"
},
"UpdatedAt": {
"type": "string",
"format": "date-time",
"title": "Updatedat"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"Id",
"ModelId",
"UpdatedByUser",
"UpdatedAt",
"Country",
"Region",
"Grouping"
],
"title": "ModelActiveHistory",
"description": "Response schema for model active history records."
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[ModelActiveHistory]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Model (/api/models/get_model_projects__team_id___project_id__models__model_id__get)
Get detailed information about a specific model.
Use this endpoint to check training status, view model configuration,
review performance metrics, and see associated jobs (predictions,
simulations, attributions).
Path Parameters:
- model_id: The IId of the model to retrieve
Response:
Detailed model object with related jobs and performance metrics.
Related:
- POST /predictions: Create a prediction with this model
- POST /simulations: Create a simulation with this model
- POST /models/{model_id}/refit: Retrain with different parameters
## GET /api/projects/{team_id}/{project_id}/models/{model_id}
Get Model
Get detailed information about a specific model.
Use this endpoint to check training status, view model configuration,
review performance metrics, and see associated jobs (predictions,
simulations, attributions).
Path Parameters:
- model_id: The IId of the model to retrieve
Response:
Detailed model object with related jobs and performance metrics.
Related:
- POST /predictions: Create a prediction with this model
- POST /simulations: Create a simulation with this model
- POST /models/{model_id}/refit: Retrain with different parameters
```json
{
"tags": [
"Models"
],
"summary": "Get Model",
"description": "Get detailed information about a specific model.\n\nUse this endpoint to check training status, view model configuration,\nreview performance metrics, and see associated jobs (predictions,\nsimulations, attributions).\n\nPath Parameters:\n - model_id: The IId of the model to retrieve\n\nResponse:\n Detailed model object with related jobs and performance metrics.\n\nRelated:\n - POST /predictions: Create a prediction with this model\n - POST /simulations: Create a simulation with this model\n - POST /models/{model_id}/refit: Retrain with different parameters",
"operationId": "get_model_projects__team_id___project_id__models__model_id__get",
"parameters": [
{
"name": "model_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide the Model IId",
"title": "Model Id"
},
"description": "Provide the Model IId"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"Task": {
"anyOf": [
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"Topic": {
"type": "string",
"enum": [
"ATTRIBUTIONSET",
"ATTRIBUTIONJOB",
"SIMULATIONJOB",
"PREDICTIONJOB",
"TRAINJOB",
"DATASET",
"DATAUPLOAD",
"GRAPHCONSTRUCT",
"GENERAL",
"OPTIMIZATIONJOB",
"RESPOSNSECURVEJOB",
"PRIORPOSTERIORJOB",
"EXCELJOB",
"GRAPHBASIC",
"FEATUREIMPORTANCE",
"GRAPHSYNERGY"
],
"title": "TaskTopics",
"description": "Task topics."
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"Id",
"Config",
"Topic",
"Status"
],
"title": "Task",
"description": "Reference task."
},
{
"type": "null"
}
]
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active model for its market segment"
},
"Country": {
"type": "string",
"title": "Country",
"description": "Country code from modelling combination (e.g., 'USA', 'GBR')"
},
"Region": {
"type": "string",
"title": "Region",
"description": "Region code from modelling combination (e.g., 'all', 'northeast')"
},
"Grouping": {
"type": "string",
"title": "Grouping",
"description": "Grouping code from modelling combination (e.g., 'all', 'retail')"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Model training completion timestamp"
},
"Parameters": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Parameters",
"description": "Model training hyperparameters and configuration"
},
"Seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Seed used for reproducible model training"
},
"GraphInstance": {
"anyOf": [
{
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"HasFinished": {
"type": "boolean",
"title": "Hasfinished"
},
"Graph": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"InstancesJobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Instancesjobid"
},
"HasFinished": {
"type": "boolean",
"title": "Hasfinished"
}
},
"type": "object",
"required": [
"Id",
"HasFinished"
],
"title": "GraphsRef",
"description": "Reference schema for graphs."
}
},
"type": "object",
"required": [
"Id",
"HasFinished",
"Graph"
],
"title": "GraphsInstanceGraph",
"description": "Reference schema for graph instantiations with graph info."
},
{
"type": "null"
}
],
"description": "Graph instance defining model structure"
},
"SimulationJobs": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"IsFromOptimization": {
"type": "boolean",
"title": "Isfromoptimization",
"description": "Whether this simulation was submitted by an optimization job.",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"IsFromOptimization"
],
"title": "SimulationJobsRef",
"description": "Reference schema for simulation Job."
},
"type": "array",
"title": "Simulationjobs",
"description": "Simulation jobs that used this model"
},
"PredictionJobs": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status"
],
"title": "PredictionJobsRef",
"description": "Reference schema for prediction job."
},
"type": "array",
"title": "Predictionjobs",
"description": "Prediction jobs that used this model"
},
"PriorPosteriorJobs": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
}
},
"type": "object",
"required": [
"IId",
"JobId"
],
"title": "PriorPosteriorJobs",
"description": "Reference schema to prior posterior job."
},
"type": "array",
"title": "Priorposteriorjobs",
"description": "Prior/posterior analysis jobs for this model"
},
"FullPrediction": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status"
],
"title": "PredictionJobsRef",
"description": "Reference schema for prediction job."
},
{
"type": "null"
}
],
"description": "Full-period prediction job (if generated)"
},
"OptimizationJobs": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"type": "integer",
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
}
},
"type": "object",
"required": [
"IId",
"JobId",
"Status"
],
"title": "OptimizationJobsRef",
"description": "Reference schema for optimization job."
},
"type": "array",
"title": "Optimizationjobs",
"description": "Optimization jobs that used this model"
},
"Attributions": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
},
"type": "array",
"title": "Attributions",
"description": "Attribution jobs that used this model"
},
"FitAttribution": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
},
{
"type": "null"
}
],
"description": "In-sample attribution job for model fit validation"
},
"ModelPerformance": {
"anyOf": [
{
"items": {
"properties": {
"Variable": {
"type": "string",
"title": "Variable"
},
"Stage": {
"type": "string",
"title": "Stage"
},
"Metric": {
"type": "string",
"title": "Metric"
},
"Value": {
"type": "number",
"title": "Value"
}
},
"type": "object",
"required": [
"Variable",
"Stage",
"Metric",
"Value"
],
"title": "ModelPerformace",
"description": "Model performance."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Modelperformance",
"description": "Model accuracy metrics (R², MAPE, etc.)"
},
"FitPriorPosterior": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
}
},
"type": "object",
"required": [
"IId",
"JobId"
],
"title": "PriorPosteriorJobs",
"description": "Reference schema to prior posterior job."
},
{
"type": "null"
}
],
"description": "In-sample prior/posterior analysis for model fit"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Selected",
"Country",
"Region",
"Grouping",
"CreatedDate",
"SimulationJobs",
"PredictionJobs",
"PriorPosteriorJobs",
"OptimizationJobs",
"Attributions"
],
"title": "DetailedModel",
"description": "Detailed response schema for trained models with related jobs.",
"examples": [
{
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Grouping": "all",
"IId": 1,
"JobId": 123,
"Name": "USA All Model",
"Note": "Model for USA market",
"Parameters": {
"epochs": 500,
"learning_rate": 0.01
},
"Region": "all",
"Selected": true,
"Status": "completed",
"UIFilterAttributions": [],
"UIFilterOptimizationJobs": [],
"UIFilterPredictionJobs": [],
"UIFilterPriorPosteriorJobs": [],
"UIFilterSimulationJobs": []
}
]
}
}
}
},
"404": {
"description": "Model not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Model (/api/models/update_model_projects__team_id___project_id__models__model_id__patch)
Update metadata attributes of a model.
Allows modification of mutable fields like Name and Note. Cannot modify
training parameters or model weights after training.
Response:
Updated model object with all current attributes.
## PATCH /api/projects/{team_id}/{project_id}/models/{model_id}
Update Model
Update metadata attributes of a model.
Allows modification of mutable fields like Name and Note. Cannot modify
training parameters or model weights after training.
Response:
Updated model object with all current attributes.
```json
{
"tags": [
"Models"
],
"summary": "Update Model",
"description": "Update metadata attributes of a model.\n\nAllows modification of mutable fields like Name and Note. Cannot modify\ntraining parameters or model weights after training.\n\nResponse:\n Updated model object with all current attributes.",
"operationId": "update_model_projects__team_id___project_id__models__model_id__patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "model_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide the Model IId",
"title": "Model Id"
},
"description": "Provide the Model IId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Description for the model/dataset"
}
},
"type": "object",
"title": "PatchModels",
"description": "Schema for updating models attribute.",
"examples": [
{
"Name": "USA National Marketing Mix Model v2",
"Note": "Updated model with seasonal adjustments and improved fit"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active model for its market segment"
},
"Country": {
"type": "string",
"title": "Country",
"description": "Country code from modelling combination (e.g., 'USA', 'GBR')"
},
"Region": {
"type": "string",
"title": "Region",
"description": "Region code from modelling combination (e.g., 'all', 'northeast')"
},
"Grouping": {
"type": "string",
"title": "Grouping",
"description": "Grouping code from modelling combination (e.g., 'all', 'retail')"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Model training completion timestamp"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Selected",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "Models",
"description": "Response schema for trained models listing and summary views.",
"examples": [
{
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Grouping": "all",
"IId": 1,
"JobId": 123,
"Name": "USA All Model",
"Note": "Model for USA market",
"Region": "all",
"Selected": true,
"Status": "completed"
}
]
}
}
}
},
"404": {
"description": "Model not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Model (/api/models/delete_model_projects__team_id___project_id__models__model_id__delete)
Delete a model and its associated data.
Marks the model for deletion and triggers background cleanup. The deletion
is asynchronous - the model is immediately hidden from listings but data
cleanup happens in the background.
Path Parameters:
- model_id: The IId of the model to delete
Restrictions:
- Cannot delete the currently active (Selected=True) model
- Cannot delete models with active attribution sets
Response:
- message: Confirmation that deletion is in progress
Notes:
- Deletion is permanent and cannot be undone
- All predictions and simulations using this model are also deleted
- Deactivate the model first if it's currently active
## DELETE /api/projects/{team_id}/{project_id}/models/{model_id}
Delete Model
Delete a model and its associated data.
Marks the model for deletion and triggers background cleanup. The deletion
is asynchronous - the model is immediately hidden from listings but data
cleanup happens in the background.
Path Parameters:
- model_id: The IId of the model to delete
Restrictions:
- Cannot delete the currently active (Selected=True) model
- Cannot delete models with active attribution sets
Response:
- message: Confirmation that deletion is in progress
Notes:
- Deletion is permanent and cannot be undone
- All predictions and simulations using this model are also deleted
- Deactivate the model first if it's currently active
```json
{
"tags": [
"Models"
],
"summary": "Delete Model",
"description": "Delete a model and its associated data.\n\nMarks the model for deletion and triggers background cleanup. The deletion\nis asynchronous - the model is immediately hidden from listings but data\ncleanup happens in the background.\n\nPath Parameters:\n - model_id: The IId of the model to delete\n\nRestrictions:\n - Cannot delete the currently active (Selected=True) model\n - Cannot delete models with active attribution sets\n\nResponse:\n - message: Confirmation that deletion is in progress\n\nNotes:\n - Deletion is permanent and cannot be undone\n - All predictions and simulations using this model are also deleted\n - Deactivate the model first if it's currently active",
"operationId": "delete_model_projects__team_id___project_id__models__model_id__delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "model_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide the Model IId",
"title": "Model Id"
},
"description": "Provide the Model IId"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"description": "Cannot delete model: model is currently active (Selected=True) or has active attribution sets. Deactivate first.",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Model not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Activate Model (/api/models/activate_model_projects__team_id___project_id__models__model_id__activate_post)
Set a model as the active model for its market segment.
The active model is the default used by the UI for dashboards and
can be referenced using "active" in API requests. Only one model
per modelling combination (country/region/grouping) can be active.
Path Parameters:
- model_id: The IId of the model to activate
Effects:
- Sets Selected=True for this model
- Deactivates any previously active model in the same segment
- UI dashboards will reflect the new active model
Prerequisites:
Model Status should be COMPLETED for meaningful activation.
Related:
- GET /models: List models to find one to activate
- DELETE /models/{model_id}: Cannot delete active models
## POST /api/projects/{team_id}/{project_id}/models/{model_id}/activate
Activate Model
Set a model as the active model for its market segment.
The active model is the default used by the UI for dashboards and
can be referenced using "active" in API requests. Only one model
per modelling combination (country/region/grouping) can be active.
Path Parameters:
- model_id: The IId of the model to activate
Effects:
- Sets Selected=True for this model
- Deactivates any previously active model in the same segment
- UI dashboards will reflect the new active model
Prerequisites:
Model Status should be COMPLETED for meaningful activation.
Related:
- GET /models: List models to find one to activate
- DELETE /models/{model_id}: Cannot delete active models
```json
{
"tags": [
"Models"
],
"summary": "Activate Model",
"description": "Set a model as the active model for its market segment.\n\nThe active model is the default used by the UI for dashboards and\ncan be referenced using \"active\" in API requests. Only one model\nper modelling combination (country/region/grouping) can be active.\n\nPath Parameters:\n - model_id: The IId of the model to activate\n\nEffects:\n - Sets Selected=True for this model\n - Deactivates any previously active model in the same segment\n - UI dashboards will reflect the new active model\n\nPrerequisites:\n Model Status should be COMPLETED for meaningful activation.\n\nRelated:\n - GET /models: List models to find one to activate\n - DELETE /models/{model_id}: Cannot delete active models",
"operationId": "activate_model_projects__team_id___project_id__models__model_id__activate_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "model_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide the Model IId",
"title": "Model Id"
},
"description": "Provide the Model IId"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Model not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Deactivate Model (/api/models/deactivate_model_projects__team_id___project_id__models__model_id__activate_delete)
Deactivate the active model for its market segment.
Clears the active state of the specified model. After this call the
market segment (country/region/grouping) will have no active model
until a new one is activated.
Path Parameters:
- model_id: The IId of the model to deactivate
Errors:
- 400 if the model is not currently active
## DELETE /api/projects/{team_id}/{project_id}/models/{model_id}/activate
Deactivate Model
Deactivate the active model for its market segment.
Clears the active state of the specified model. After this call the
market segment (country/region/grouping) will have no active model
until a new one is activated.
Path Parameters:
- model_id: The IId of the model to deactivate
Errors:
- 400 if the model is not currently active
```json
{
"tags": [
"Models"
],
"summary": "Deactivate Model",
"description": "Deactivate the active model for its market segment.\n\nClears the active state of the specified model. After this call the\nmarket segment (country/region/grouping) will have no active model\nuntil a new one is activated.\n\nPath Parameters:\n - model_id: The IId of the model to deactivate\n\nErrors:\n - 400 if the model is not currently active",
"operationId": "deactivate_model_projects__team_id___project_id__models__model_id__activate_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "model_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide the Model IId",
"title": "Model Id"
},
"description": "Provide the Model IId"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Model not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Project Model Target Nodes (/api/models/project_model_target_nodes_projects__team_id___project_id__model_target_nodes_get)
Get the distinct target Variables across all models in a project.
Returns the union of Variables flagged ``TargetNode=True`` in any
non-deleted model that belongs to the given project.
## GET /api/projects/{team_id}/{project_id}/model_target_nodes
Project Model Target Nodes
Get the distinct target Variables across all models in a project.
Returns the union of Variables flagged ``TargetNode=True`` in any
non-deleted model that belongs to the given project.
```json
{
"tags": [
"Models"
],
"summary": "Project Model Target Nodes",
"description": "Get the distinct target Variables across all models in a project.\n\nReturns the union of Variables flagged ``TargetNode=True`` in any\nnon-deleted model that belongs to the given project.",
"operationId": "project_model_target_nodes_projects__team_id___project_id__model_target_nodes_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid",
"description": "Variable identifier"
},
"Slug": {
"type": "string",
"title": "Slug",
"description": "Unique variable key in format 'source-type-attributes'"
},
"Name": {
"type": "string",
"title": "Name",
"description": "Human-readable display name"
},
"Type": {
"description": "Variable category: Sales, Media, Macro, Price, etc.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes"
},
"Group": {
"description": "Functional grouping: KPI, Input, Volume, etc.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups"
},
"MinLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Minlimit",
"description": "Project-level lower bound for this variable. Used as the attribution reference point and as a hard lower bound on user-supplied values in simulation/prediction/optimization/response-curve/attribution-baseline inputs. NULL means no enforced lower bound."
},
"MaxLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Maxlimit",
"description": "Project-level upper bound for this variable. Hard upper bound on user-supplied values in simulation/prediction/optimization/response-curve/attribution-baseline inputs. NULL means no enforced upper bound."
},
"util_attr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
],
"description": "Parsed variable attributes (Product, Media, Campaign, etc.)"
}
},
"type": "object",
"required": [
"IId",
"Slug",
"Name",
"Type",
"Group"
],
"title": "Variable",
"description": "Response schema for variable metadata.",
"examples": [
{
"Group": "Sales",
"IId": 1,
"Name": "Health Units Sold",
"Slug": "file-sales-product-health-metric-units_sold",
"Type": "Sales",
"util_attr": {
"Metric": "UnitsSold",
"Product": "Health"
}
}
]
},
"title": "Response Project Model Target Nodes Projects Team Id Project Id Model Target Nodes Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Project Model Result Nodes (/api/models/project_model_result_nodes_projects__team_id___project_id__model_result_nodes_get)
Get the distinct result Variables across all models in a project.
Returns the union of Variables flagged ``ResultNode=True`` in any
non-deleted model that belongs to the given project.
## GET /api/projects/{team_id}/{project_id}/model_result_nodes
Project Model Result Nodes
Get the distinct result Variables across all models in a project.
Returns the union of Variables flagged ``ResultNode=True`` in any
non-deleted model that belongs to the given project.
```json
{
"tags": [
"Models"
],
"summary": "Project Model Result Nodes",
"description": "Get the distinct result Variables across all models in a project.\n\nReturns the union of Variables flagged ``ResultNode=True`` in any\nnon-deleted model that belongs to the given project.",
"operationId": "project_model_result_nodes_projects__team_id___project_id__model_result_nodes_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid",
"description": "Variable identifier"
},
"Slug": {
"type": "string",
"title": "Slug",
"description": "Unique variable key in format 'source-type-attributes'"
},
"Name": {
"type": "string",
"title": "Name",
"description": "Human-readable display name"
},
"Type": {
"description": "Variable category: Sales, Media, Macro, Price, etc.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes"
},
"Group": {
"description": "Functional grouping: KPI, Input, Volume, etc.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups"
},
"MinLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Minlimit",
"description": "Project-level lower bound for this variable. Used as the attribution reference point and as a hard lower bound on user-supplied values in simulation/prediction/optimization/response-curve/attribution-baseline inputs. NULL means no enforced lower bound."
},
"MaxLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Maxlimit",
"description": "Project-level upper bound for this variable. Hard upper bound on user-supplied values in simulation/prediction/optimization/response-curve/attribution-baseline inputs. NULL means no enforced upper bound."
},
"util_attr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
],
"description": "Parsed variable attributes (Product, Media, Campaign, etc.)"
}
},
"type": "object",
"required": [
"IId",
"Slug",
"Name",
"Type",
"Group"
],
"title": "Variable",
"description": "Response schema for variable metadata.",
"examples": [
{
"Group": "Sales",
"IId": 1,
"Name": "Health Units Sold",
"Slug": "file-sales-product-health-metric-units_sold",
"Type": "Sales",
"util_attr": {
"Metric": "UnitsSold",
"Product": "Health"
}
}
]
},
"title": "Response Project Model Result Nodes Projects Team Id Project Id Model Result Nodes Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Project Model Input Nodes (/api/models/project_model_input_nodes_projects__team_id___project_id__model_input_nodes_get)
Get the distinct input Variables across all models in a project.
Returns the union of Variables flagged ``InputNode=True`` in any
non-deleted model that belongs to the given project.
## GET /api/projects/{team_id}/{project_id}/model_input_nodes
Project Model Input Nodes
Get the distinct input Variables across all models in a project.
Returns the union of Variables flagged ``InputNode=True`` in any
non-deleted model that belongs to the given project.
```json
{
"tags": [
"Models"
],
"summary": "Project Model Input Nodes",
"description": "Get the distinct input Variables across all models in a project.\n\nReturns the union of Variables flagged ``InputNode=True`` in any\nnon-deleted model that belongs to the given project.",
"operationId": "project_model_input_nodes_projects__team_id___project_id__model_input_nodes_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid",
"description": "Variable identifier"
},
"Slug": {
"type": "string",
"title": "Slug",
"description": "Unique variable key in format 'source-type-attributes'"
},
"Name": {
"type": "string",
"title": "Name",
"description": "Human-readable display name"
},
"Type": {
"description": "Variable category: Sales, Media, Macro, Price, etc.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes"
},
"Group": {
"description": "Functional grouping: KPI, Input, Volume, etc.",
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups"
},
"MinLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Minlimit",
"description": "Project-level lower bound for this variable. Used as the attribution reference point and as a hard lower bound on user-supplied values in simulation/prediction/optimization/response-curve/attribution-baseline inputs. NULL means no enforced lower bound."
},
"MaxLimit": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Maxlimit",
"description": "Project-level upper bound for this variable. Hard upper bound on user-supplied values in simulation/prediction/optimization/response-curve/attribution-baseline inputs. NULL means no enforced upper bound."
},
"util_attr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
],
"description": "Parsed variable attributes (Product, Media, Campaign, etc.)"
}
},
"type": "object",
"required": [
"IId",
"Slug",
"Name",
"Type",
"Group"
],
"title": "Variable",
"description": "Response schema for variable metadata.",
"examples": [
{
"Group": "Sales",
"IId": 1,
"Name": "Health Units Sold",
"Slug": "file-sales-product-health-metric-units_sold",
"Type": "Sales",
"util_attr": {
"Metric": "UnitsSold",
"Product": "Health"
}
}
]
},
"title": "Response Project Model Input Nodes Projects Team Id Project Id Model Input Nodes Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Valid Datasets (/api/models/get_valid_datasets_projects__team_id___project_id__models__model_id__valid_datasets_get)
List datasets compatible with this model for refit or prediction.
A dataset is compatible if it contains all variables required by the
model's graph structure for the model's modelling combination
(country/region/grouping).
Path Parameters:
- model_id: The IId of the model
Response:
List of compatible datasets.
Use Cases:
- Find datasets for model refit
- Verify dataset compatibility before prediction
- Select alternative data sources for forecasting
Related:
- POST /models/{model_id}/refit: Retrain with a compatible dataset
- POST /predictions: Use compatible dataset for forecasting
## GET /api/projects/{team_id}/{project_id}/models/{model_id}/valid_datasets
Get Valid Datasets
List datasets compatible with this model for refit or prediction.
A dataset is compatible if it contains all variables required by the
model's graph structure for the model's modelling combination
(country/region/grouping).
Path Parameters:
- model_id: The IId of the model
Response:
List of compatible datasets.
Use Cases:
- Find datasets for model refit
- Verify dataset compatibility before prediction
- Select alternative data sources for forecasting
Related:
- POST /models/{model_id}/refit: Retrain with a compatible dataset
- POST /predictions: Use compatible dataset for forecasting
```json
{
"tags": [
"Models"
],
"summary": "Get Valid Datasets",
"description": "List datasets compatible with this model for refit or prediction.\n\nA dataset is compatible if it contains all variables required by the\nmodel's graph structure for the model's modelling combination\n(country/region/grouping).\n\nPath Parameters:\n - model_id: The IId of the model\n\nResponse:\n List of compatible datasets.\n\nUse Cases:\n - Find datasets for model refit\n - Verify dataset compatibility before prediction\n - Select alternative data sources for forecasting\n\nRelated:\n - POST /models/{model_id}/refit: Retrain with a compatible dataset\n - POST /predictions: Use compatible dataset for forecasting",
"operationId": "get_valid_datasets_projects__team_id___project_id__models__model_id__valid_datasets_get",
"parameters": [
{
"name": "model_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide the Model IId",
"title": "Model Id"
},
"description": "Provide the Model IId"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /datasets/{IId})"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active dataset for modeling"
},
"Name": {
"type": "string",
"title": "Name",
"description": "Dataset display name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Dataset creation timestamp"
},
"DataImports": {
"items": {
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"IId": {
"type": "integer",
"title": "Iid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"DatasetName": {
"type": "string",
"title": "Datasetname"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"External": {
"type": "boolean",
"title": "External"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"ModellingCombinations": {
"anyOf": [
{
"items": {
"properties": {
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
}
},
"type": "object",
"required": [
"Country",
"Region",
"Grouping"
],
"title": "ModellingCombinationForDataImport",
"description": "Schema for modelling combination for data import."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Modellingcombinations"
}
},
"type": "object",
"required": [
"IId",
"Date",
"DatasetName",
"Status",
"External"
],
"title": "DataImportRef",
"description": "Reference schema for data import."
},
"type": "array",
"title": "Dataimports",
"description": "List of data imports included in this dataset"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Processing state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"Blocked": {
"type": "boolean",
"title": "Blocked",
"description": "True when at least one data value falls outside this dataset's variable limits. Blocked datasets are rejected by sim/pred/attribution/optimize/response-curve submission until the limits are patched to cover the data.",
"default": false
}
},
"type": "object",
"required": [
"IId",
"Selected",
"Name",
"CreatedDate",
"DataImports",
"Status"
],
"title": "DataSet",
"description": "Response schema for datasets (collections of data imports).",
"examples": [
{
"CreatedDate": "2024-01-15T10:30:00Z",
"CreatorId": "user-123",
"DataImports": [
{
"DatasetName": "Sales",
"Date": "2024-01-15T10:30:00",
"External": false,
"IId": 1,
"Status": "complete"
}
],
"IId": 1,
"Name": "Marketing Dataset Q4",
"Note": "Combined sales and marketing data",
"Selected": true,
"Status": "complete"
}
]
},
"title": "Response Get Valid Datasets Projects Team Id Project Id Models Model Id Valid Datasets Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Refit Model (/api/models/refit_model_projects__team_id___project_id__models__model_id__refit_post)
Retrain an existing model with new data or parameters.
Creates a new model using the same graph structure as an existing model
but with updated training data, date ranges, or hyperparameters. Useful
for model refresh workflows when new data is available.
Use Cases:
- Refresh model with latest data while preserving graph structure
- Experiment with different training parameters
- Retrain on a different dataset
Response:
Returns the NEW model created from refit (not the original model).
Notes:
- Creates a new model; does not modify the source model
- The source model must have COMPLETED training
- New model inherits the graph structure but not weights
Related:
- POST /build/model: Build a completely new model
- GET /models/{model_id}/valid_datasets: Find compatible datasets
## POST /api/projects/{team_id}/{project_id}/models/{model_id}/refit
Refit Model
Retrain an existing model with new data or parameters.
Creates a new model using the same graph structure as an existing model
but with updated training data, date ranges, or hyperparameters. Useful
for model refresh workflows when new data is available.
Use Cases:
- Refresh model with latest data while preserving graph structure
- Experiment with different training parameters
- Retrain on a different dataset
Response:
Returns the NEW model created from refit (not the original model).
Notes:
- Creates a new model; does not modify the source model
- The source model must have COMPLETED training
- New model inherits the graph structure but not weights
Related:
- POST /build/model: Build a completely new model
- GET /models/{model_id}/valid_datasets: Find compatible datasets
```json
{
"tags": [
"Models"
],
"summary": "Refit Model",
"description": "Retrain an existing model with new data or parameters.\n\nCreates a new model using the same graph structure as an existing model\nbut with updated training data, date ranges, or hyperparameters. Useful\nfor model refresh workflows when new data is available.\n\nUse Cases:\n - Refresh model with latest data while preserving graph structure\n - Experiment with different training parameters\n - Retrain on a different dataset\n\nResponse:\n Returns the NEW model created from refit (not the original model).\n\nNotes:\n - Creates a new model; does not modify the source model\n - The source model must have COMPLETED training\n - New model inherits the graph structure but not weights\n\nRelated:\n - POST /build/model: Build a completely new model\n - GET /models/{model_id}/valid_datasets: Find compatible datasets",
"operationId": "refit_model_projects__team_id___project_id__models__model_id__refit_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "model_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide the Model IId",
"title": "Model Id"
},
"description": "Provide the Model IId"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"properties": {
"model_param": {
"anyOf": [
{
"properties": {
"epochs": {
"type": "integer",
"title": "The epochs",
"description": "Maximum training iterations. Model may stop earlier if early_stopping is configured. Higher values allow more learning but risk overfitting. Default (500) works for most models.",
"default": 500
},
"learning_rate": {
"type": "number",
"title": "The learning rate",
"description": "Step size for gradient descent optimization. Lower values (0.001) give more stable but slower training. Higher values (0.1) train faster but may overshoot. Default (0.01) is a good starting point.",
"default": 0.01
},
"samples": {
"type": "integer",
"title": "The samples",
"description": "Number of posterior samples during training for Bayesian inference. Higher values improve uncertainty estimates but slow training. Default (2) balances speed and quality.",
"default": 2
},
"grad_clip": {
"type": "number",
"title": "The grad clip",
"description": "Maximum gradient magnitude to prevent exploding gradients. Lower values make training more stable but may slow convergence. Default (10) is suitable for most models.",
"default": 10
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "Job queue priority from 1-100. Higher values are processed first. Model training is typically lower priority (30) since it's longer-running.",
"default": 30
}
},
"type": "object",
"title": "ModelParams",
"description": "Training hyperparameters and job settings for model building.",
"examples": [
{
"epochs": 500,
"grad_clip": 10,
"learning_rate": 0.01,
"priority": 30,
"samples": 2
}
]
},
{
"type": "null"
}
],
"description": "The parameter for the model/models. Will use default values if it's empty.",
"default": {
"epochs": 500,
"learning_rate": 0.01,
"samples": 2,
"grad_clip": 10,
"priority": 30
}
},
"model_detail": {
"anyOf": [
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
},
"train_dates": {
"anyOf": [
{
"items": {
"type": "string",
"format": "date-time"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Train Dates",
"description": "List of train dates."
},
"eval_dates": {
"anyOf": [
{
"items": {
"type": "string",
"format": "date-time"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Eval Dates",
"description": "List of eval dates."
},
"activate": {
"type": "boolean",
"title": "Activate",
"description": "Activate the model/dataset as soon as it is done training.",
"default": false
},
"early_stopping": {
"anyOf": [
{
"properties": {
"patience": {
"type": "integer",
"minimum": 1,
"title": "Patience",
"description": "How many of the last epochs should be used.",
"default": 100
},
"absolute_tolerance": {
"type": "number",
"minimum": 0,
"title": "Absolute Tolerance",
"description": "The absolute tollerance to use to determine to stop",
"default": 0.1
},
"relative_tolerance": {
"type": "number",
"minimum": 0,
"title": "Relative Tolerance",
"description": "The relative tollerance to use to determine to stop",
"default": 0.1
}
},
"type": "object",
"title": "EarlyStopping",
"description": "Config for early stopping."
},
{
"type": "null"
}
],
"description": "Early stopping configuration for the model training."
}
},
"type": "object",
"title": "ModelRefitDetail",
"description": "schemas class of model refit detail."
},
{
"type": "null"
}
],
"description": "Refit configuration: new dataset reference, updated training dates, and metadata. Uses original model's graph structure and settings.",
"default": {
"activate": false
}
}
},
"type": "object",
"title": "ModelRefitRequest",
"description": "Request body for refitting an existing model with new data or settings."
},
{
"type": "null"
}
],
"default": {
"model_param": {
"epochs": 500,
"learning_rate": 0.01,
"samples": 2,
"grad_clip": 10,
"priority": 30
},
"model_detail": {
"activate": false
}
},
"title": "Request"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active model for its market segment"
},
"Country": {
"type": "string",
"title": "Country",
"description": "Country code from modelling combination (e.g., 'USA', 'GBR')"
},
"Region": {
"type": "string",
"title": "Region",
"description": "Region code from modelling combination (e.g., 'all', 'northeast')"
},
"Grouping": {
"type": "string",
"title": "Grouping",
"description": "Grouping code from modelling combination (e.g., 'all', 'retail')"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Model training completion timestamp"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Selected",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "Models",
"description": "Response schema for trained models listing and summary views.",
"examples": [
{
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Grouping": "all",
"IId": 1,
"JobId": 123,
"Name": "USA All Model",
"Note": "Model for USA market",
"Region": "all",
"Selected": true,
"Status": "completed"
}
]
}
}
}
},
"400": {
"description": "Invalid refit request: source model not completed, invalid configuration, or dataset incompatible with model graph",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Source model not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Project is in read-only state",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Simulations (/api/simulations/list_simulations_projects__team_id___project_id__simulations_get)
List all simulation jobs in the project with optional filtering.
Returns a paginated list of simulation jobs, useful for monitoring job
status, reviewing scenario analyses, or auditing simulation history.
Query Parameters:
- filters: JSON filter expressions to narrow results
Example: '{"Status": [["=", "COMPLETED"]]}'
Response:
Paginated list of simulation jobs.
Related:
- GET /simulations/{simulation_id}: Get full details for a specific job
- POST /simulations: Create a new simulation job
## GET /api/projects/{team_id}/{project_id}/simulations
List Simulations
List all simulation jobs in the project with optional filtering.
Returns a paginated list of simulation jobs, useful for monitoring job
status, reviewing scenario analyses, or auditing simulation history.
Query Parameters:
- filters: JSON filter expressions to narrow results
Example: '{"Status": [["=", "COMPLETED"]]}'
Response:
Paginated list of simulation jobs.
Related:
- GET /simulations/{simulation_id}: Get full details for a specific job
- POST /simulations: Create a new simulation job
```json
{
"tags": [
"Simulations"
],
"summary": "List Simulations",
"description": "List all simulation jobs in the project with optional filtering.\n\nReturns a paginated list of simulation jobs, useful for monitoring job\nstatus, reviewing scenario analyses, or auditing simulation history.\n\nQuery Parameters:\n - filters: JSON filter expressions to narrow results\n Example: '{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n\nResponse:\n Paginated list of simulation jobs.\n\nRelated:\n - GET /simulations/{simulation_id}: Get full details for a specific job\n - POST /simulations: Create a new simulation job",
"operationId": "list_simulations_projects__team_id___project_id__simulations_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Multiple filters create OR logic.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By model ID: filters='{\"Model.IId\": [[\"=\", \"42\"]]}'\n - By scenario dates: filters='{\"ScenarioStartDate\": [[\">=\", \"2024-01-01\"]]}'\n - Recent simulations: filters='{\"Date\": [[\">=\", \"2024-10-01\"]]}'\n - By dataset: filters='{\"DataSet.Name\": [[\"contains\", \"Marketing\"]]}'\n - With notes only: filters='{\"Note\": [[\"isnot\", \"NULL\"]]}'\n - Sort by date: filters='{\"Date\": [[\"orderby\", \"desc\"]]}'\n - Name search: filters='{\"Name\": [[\"similarity\", \"scenario analysis\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby, similarity\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Multiple filters create OR logic.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By model ID: filters='{\"Model.IId\": [[\"=\", \"42\"]]}'\n - By scenario dates: filters='{\"ScenarioStartDate\": [[\">=\", \"2024-01-01\"]]}'\n - Recent simulations: filters='{\"Date\": [[\">=\", \"2024-10-01\"]]}'\n - By dataset: filters='{\"DataSet.Name\": [[\"contains\", \"Marketing\"]]}'\n - With notes only: filters='{\"Note\": [[\"isnot\", \"NULL\"]]}'\n - Sort by date: filters='{\"Date\": [[\"orderby\", \"desc\"]]}'\n - Name search: filters='{\"Name\": [[\"similarity\", \"scenario analysis\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby, similarity\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"Model": {
"description": "Reference to the trained model used for this simulation",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"ScenarioStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Scenariostartdate",
"description": "Start date for scenario comparison period"
},
"ScenarioEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Scenarioenddate",
"description": "End date for scenario comparison period"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Date",
"Model"
],
"title": "SimulationJobs",
"description": "Response schema for simulation jobs listing and summary views.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 456,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Q4 Sales Simulation",
"Note": "Simulation for Q4 marketing scenarios",
"ScenarioEndDate": "2024-12-31T00:00:00",
"ScenarioStartDate": "2024-01-01T00:00:00",
"Status": "completed"
}
]
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[SimulationJobs]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Submit Simulation (/api/simulations/submit_simulation_projects__team_id___project_id__simulations_post)
Submit a simulation job to compare baseline vs scenario forecasts.
Use simulations for "what-if" analysis comparing a baseline scenario against
one or more alternative scenarios with modified input variables (e.g., increased
marketing spend, pricing changes). Unlike predictions which forecast absolute
values, simulations emphasize the differential impact between scenarios.
Workflow:
1. Ensure you have a trained model (see POST /build/model)
2. Define BaseScenario and Scenario variable updates in updated_values
3. Submit simulation with this endpoint
4. Poll GET /simulations/{simulation_id} until Status is COMPLETED
5. Retrieve comparative results via GET /simulations/{simulation_id}/data
Response:
Returns the created simulation job. Poll status until COMPLETED.
Related:
- GET /simulations/{simulation_id}: Poll job status
- GET /simulations/{simulation_id}/data: Download comparison results
- POST /predictions: Use for absolute forecasts (not comparative)
- POST /optimizations: Use for budget allocation optimization
## POST /api/projects/{team_id}/{project_id}/simulations
Submit Simulation
Submit a simulation job to compare baseline vs scenario forecasts.
Use simulations for "what-if" analysis comparing a baseline scenario against
one or more alternative scenarios with modified input variables (e.g., increased
marketing spend, pricing changes). Unlike predictions which forecast absolute
values, simulations emphasize the differential impact between scenarios.
Workflow:
1. Ensure you have a trained model (see POST /build/model)
2. Define BaseScenario and Scenario variable updates in updated_values
3. Submit simulation with this endpoint
4. Poll GET /simulations/{simulation_id} until Status is COMPLETED
5. Retrieve comparative results via GET /simulations/{simulation_id}/data
Response:
Returns the created simulation job. Poll status until COMPLETED.
Related:
- GET /simulations/{simulation_id}: Poll job status
- GET /simulations/{simulation_id}/data: Download comparison results
- POST /predictions: Use for absolute forecasts (not comparative)
- POST /optimizations: Use for budget allocation optimization
```json
{
"tags": [
"Simulations"
],
"summary": "Submit Simulation",
"description": "Submit a simulation job to compare baseline vs scenario forecasts.\n\nUse simulations for \"what-if\" analysis comparing a baseline scenario against\none or more alternative scenarios with modified input variables (e.g., increased\nmarketing spend, pricing changes). Unlike predictions which forecast absolute\nvalues, simulations emphasize the differential impact between scenarios.\n\nWorkflow:\n 1. Ensure you have a trained model (see POST /build/model)\n 2. Define BaseScenario and Scenario variable updates in updated_values\n 3. Submit simulation with this endpoint\n 4. Poll GET /simulations/{simulation_id} until Status is COMPLETED\n 5. Retrieve comparative results via GET /simulations/{simulation_id}/data\n\nResponse:\n Returns the created simulation job. Poll status until COMPLETED.\n\nRelated:\n - GET /simulations/{simulation_id}: Poll job status\n - GET /simulations/{simulation_id}/data: Download comparison results\n - POST /predictions: Use for absolute forecasts (not comparative)\n - POST /optimizations: Use for budget allocation optimization",
"operationId": "submit_simulation_projects__team_id___project_id__simulations_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"model_param": {
"anyOf": [
{
"properties": {
"samples": {
"type": "integer",
"title": "The samples",
"description": "Number of posterior samples to draw for uncertainty estimation. Higher values (e.g., 50-100) give smoother uncertainty bands but take longer. Default (20) is suitable for most use cases.",
"default": 20
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "Job queue priority from 1-100. Higher values are processed first. Use higher priority for time-sensitive simulations. Default (60) is standard priority.",
"default": 60
}
},
"type": "object",
"title": "SimulationParams",
"description": "Sampling and job parameters for simulation execution.",
"examples": [
{
"priority": 60,
"samples": 20
}
]
},
{
"type": "null"
}
],
"description": "Sampling parameters controlling uncertainty estimation. 'samples' determines posterior draws (more = better uncertainty, slower). 'priority' sets job queue priority (higher = processed sooner).",
"default": {
"samples": 20,
"priority": 60
}
},
"simulation_detail": {
"description": "Core simulation configuration: model to use, date range for comparison, and dataset reference. Required fields: model_id. For custom date ranges, provide start_date and end_date.",
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Start Date",
"description": "Start of the scenario comparison period. Use ISO 8601 format (e.g., '2024-01-01T00:00:00'). Must align with project periodicity."
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "End Date",
"description": "End of the scenario comparison period. Use ISO 8601 format. Must be after start_date and align with project periodicity."
},
"early_stopping": {
"anyOf": [
{
"properties": {
"patience": {
"type": "integer",
"minimum": 1,
"title": "Patience",
"description": "How many of the last epochs should be used.",
"default": 100
},
"absolute_tolerance": {
"type": "number",
"minimum": 0,
"title": "Absolute Tolerance",
"description": "The absolute tollerance to use to determine to stop",
"default": 0.1
},
"relative_tolerance": {
"type": "number",
"minimum": 0,
"title": "Relative Tolerance",
"description": "The relative tollerance to use to determine to stop",
"default": 0.1
}
},
"type": "object",
"title": "EarlyStopping",
"description": "Config for early stopping."
},
{
"type": "null"
}
],
"description": "Early stopping configuration to halt simulation if convergence criteria are met. Reduces computation time for stable simulations."
},
"model_id": {
"type": "integer",
"title": "Model Id",
"description": "IId of the trained model to use. Model must have Status=COMPLETED. Get available models from GET /models endpoint."
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Dataset IId to use. Omit or pass 'active' for the project's active dataset. Dataset must be compatible with the model's variables."
},
"quantiles": {
"anyOf": [
{
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Quantiles",
"description": "Uncertainty percentiles to compute (1-100). Higher values capture more uncertainty. Common: [20, 40, 50, 60, 80] for median + ranges. Legacy placement kept for compatibility: prefer the top-level 'quantiles' on the request, matching predictions and attributions.",
"default": [
20,
40,
50,
60,
80
]
},
"additional_config": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Additional Config",
"description": "UI-specific configuration passed through to frontend display."
}
},
"type": "object",
"required": [
"model_id"
],
"title": "SimulationDetail",
"examples": [
{
"dataset_id": "active",
"end_date": "2024-12-31T00:00:00",
"model_id": 1,
"name": "Q4 Sales Simulation",
"note": "Simulating media spend scenarios for Q4",
"quantiles": [
20,
40,
50,
60,
80
],
"start_date": "2024-01-01T00:00:00"
}
]
},
"updated_values": {
"additionalProperties": {
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable"
},
"update": {
"anyOf": [
{
"items": {
"prefixItems": [
{
"type": "string",
"format": "date-time",
"title": "Date"
},
{
"type": "number",
"title": "Value"
}
],
"type": "array",
"maxItems": 2,
"minItems": 2
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Update"
}
},
"type": "object",
"required": [
"variable",
"update"
],
"title": "UpdatedVariable",
"description": "Schema for schenario updated variabls values."
},
"type": "array"
},
"propertyNames": {
"enum": [
"BaseScenario",
"Scenario"
]
},
"type": "object",
"title": "Updated Values",
"description": "Variable modifications for scenario comparison. Dict with keys 'BaseScenario' and 'Scenario', each containing list of {variable, update} objects. 'update' is a list of values matching the date range length."
},
"quantiles": {
"anyOf": [
{
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Quantiles",
"description": "Uncertainty percentiles to compute (1-100). Common: [20, 40, 50, 60, 80] for median + ranges. Also accepted at 'simulation_detail.quantiles' (legacy placement); this field wins if both are set.",
"default": [
20,
40,
50,
60,
80
]
},
"attributions": {
"items": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"samples": {
"type": "integer",
"title": "The samples",
"description": "Hom many subsamples to draw from the posterior distribution. The higher number of samples the better the uncertainty estimation becomes but it also takes longer to run.",
"default": 20
},
"baseline": {
"anyOf": [
{
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable",
"description": "Variable slug."
},
"baseline": {
"type": "number",
"title": "Baseline",
"description": "Set baseline."
}
},
"type": "object",
"required": [
"variable",
"baseline"
],
"title": "ReferencePointBaseline",
"description": "Attribution job baseline."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Baseline"
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
},
"quantiles": {
"anyOf": [
{
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Quantiles",
"default": [
1,
25,
50,
75,
99
]
},
"referece_point_fallback": {
"anyOf": [
{
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback",
"description": "Attribution's reference point fallback."
},
{
"type": "null"
}
],
"description": "Reference point fallback.",
"default": "Min"
},
"predicted_targets_as_data": {
"type": "boolean",
"title": "Predicted Targets As Data",
"description": "Set predicted targets as data.",
"default": true
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Optional integer seed. If omitted, the chained attribution inherits the parent job's seed."
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Start Date",
"description": "The first date in the date range used to select data from the dataset"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "End Date",
"description": "The last date in the date range used to select data from the dataset."
},
"simulation_scenario": {
"type": "string",
"enum": [
"BaseScenario",
"Scenario"
],
"title": "Simulation Scenario",
"description": "Simulation scenario to run attribution.",
"default": "Scenario"
},
"simulation_quantile": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "Simulation Quantile",
"description": "Simulation quantile to run attribution.",
"default": 50
}
},
"type": "object",
"title": "SimulationAttribution",
"description": "Run attribution after simulation job."
},
"type": "array",
"title": "Attributions",
"description": "Optional attribution jobs to auto-create after simulation completes. Use to analyze which variables drove the scenario differences."
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Optional integer seed for reproducible runs. If omitted, the server generates a random seed."
},
"validate_limits": {
"type": "boolean",
"title": "Validate Limits",
"description": "Validate values against per-variable min/max limits.",
"default": false
}
},
"type": "object",
"required": [
"simulation_detail",
"updated_values"
],
"title": "SimulationRequest",
"description": "Request body for creating a simulation job to compare scenarios.",
"examples": [
{
"attributions": [
{
"name": "Scenario Attribution",
"priority": 30,
"quantiles": [
1,
25,
50,
75,
99
],
"samples": 20,
"simulation_quantile": 50,
"simulation_scenario": "Scenario"
}
],
"model_param": {
"priority": 60,
"samples": 20
},
"quantiles": [
20,
40,
50,
60,
80
],
"simulation_detail": {
"dataset_id": "active",
"end_date": "2024-12-31T00:00:00",
"model_id": 1,
"name": "Q4 Media Spend Simulation",
"note": "Comparing baseline vs increased media spend",
"start_date": "2024-01-01T00:00:00"
},
"updated_values": {
"BaseScenario": [
{
"update": [
[
"2024-01-01T00:00:00",
10000
],
[
"2024-02-01T00:00:00",
10000
],
[
"2024-03-01T00:00:00",
10000
]
],
"variable": "tv_spend"
},
{
"update": [
[
"2024-01-01T00:00:00",
5000
],
[
"2024-02-01T00:00:00",
5000
],
[
"2024-03-01T00:00:00",
5000
]
],
"variable": "digital_spend"
}
],
"Scenario": [
{
"update": [
[
"2024-01-01T00:00:00",
15000
],
[
"2024-02-01T00:00:00",
15000
],
[
"2024-03-01T00:00:00",
15000
]
],
"variable": "tv_spend"
},
{
"update": [
[
"2024-01-01T00:00:00",
7500
],
[
"2024-02-01T00:00:00",
7500
],
[
"2024-03-01T00:00:00",
7500
]
],
"variable": "digital_spend"
}
]
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"Model": {
"description": "Reference to the trained model used for this simulation",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"ScenarioStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Scenariostartdate",
"description": "Start date for scenario comparison period"
},
"ScenarioEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Scenarioenddate",
"description": "End date for scenario comparison period"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Date",
"Model"
],
"title": "SimulationJobs",
"description": "Response schema for simulation jobs listing and summary views.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 456,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Q4 Sales Simulation",
"Note": "Simulation for Q4 marketing scenarios",
"ScenarioEndDate": "2024-12-31T00:00:00",
"ScenarioStartDate": "2024-01-01T00:00:00",
"Status": "completed"
}
]
}
}
}
},
"400": {
"description": "Invalid simulation request: model not found, invalid date range, invalid scenario configuration, or dataset incompatible with model",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Project is in read-only state",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Bulk Delete Simulations (/api/simulations/bulk_delete_simulations_projects__team_id___project_id__simulations_delete)
Bulk delete simulation jobs matching the given filters.
Marks all matching jobs for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
## DELETE /api/projects/{team_id}/{project_id}/simulations
Bulk Delete Simulations
Bulk delete simulation jobs matching the given filters.
Marks all matching jobs for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
```json
{
"tags": [
"Simulations"
],
"summary": "Bulk Delete Simulations",
"description": "Bulk delete simulation jobs matching the given filters.\n\nMarks all matching jobs for deletion and publishes delete messages to\nRabbitMQ concurrently in the background via a single DB round-trip each.",
"operationId": "bulk_delete_simulations_projects__team_id___project_id__simulations_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /simulations.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By date: filters='{\"Date\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /simulations.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By date: filters='{\"Date\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n "
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Simulation (/api/simulations/get_simulation_projects__team_id___project_id__simulations__simulation_id__get)
Get detailed information about a specific simulation job.
Use this endpoint to check job status, view scenario configurations,
and access metadata. Poll this endpoint until Status is COMPLETED
before downloading results.
Path Parameters:
- simulation_id: The IId of the simulation job to retrieve
Response:
Detailed simulation job object with scenario configurations and task progress.
Related:
- GET /simulations/{simulation_id}/data: Download results (after COMPLETED)
- DELETE /simulations/{simulation_id}: Remove the simulation job
## GET /api/projects/{team_id}/{project_id}/simulations/{simulation_id}
Get Simulation
Get detailed information about a specific simulation job.
Use this endpoint to check job status, view scenario configurations,
and access metadata. Poll this endpoint until Status is COMPLETED
before downloading results.
Path Parameters:
- simulation_id: The IId of the simulation job to retrieve
Response:
Detailed simulation job object with scenario configurations and task progress.
Related:
- GET /simulations/{simulation_id}/data: Download results (after COMPLETED)
- DELETE /simulations/{simulation_id}: Remove the simulation job
```json
{
"tags": [
"Simulations"
],
"summary": "Get Simulation",
"description": "Get detailed information about a specific simulation job.\n\nUse this endpoint to check job status, view scenario configurations,\nand access metadata. Poll this endpoint until Status is COMPLETED\nbefore downloading results.\n\nPath Parameters:\n - simulation_id: The IId of the simulation job to retrieve\n\nResponse:\n Detailed simulation job object with scenario configurations and task progress.\n\nRelated:\n - GET /simulations/{simulation_id}/data: Download results (after COMPLETED)\n - DELETE /simulations/{simulation_id}: Remove the simulation job",
"operationId": "get_simulation_projects__team_id___project_id__simulations__simulation_id__get",
"parameters": [
{
"name": "simulation_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide simulation IId",
"title": "Simulation Id"
},
"description": "Provide simulation IId"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"Task": {
"anyOf": [
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"Topic": {
"type": "string",
"enum": [
"ATTRIBUTIONSET",
"ATTRIBUTIONJOB",
"SIMULATIONJOB",
"PREDICTIONJOB",
"TRAINJOB",
"DATASET",
"DATAUPLOAD",
"GRAPHCONSTRUCT",
"GENERAL",
"OPTIMIZATIONJOB",
"RESPOSNSECURVEJOB",
"PRIORPOSTERIORJOB",
"EXCELJOB",
"GRAPHBASIC",
"FEATUREIMPORTANCE",
"GRAPHSYNERGY"
],
"title": "TaskTopics",
"description": "Task topics."
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"Id",
"Config",
"Topic",
"Status"
],
"title": "Task",
"description": "Reference task."
},
{
"type": "null"
}
]
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"Model": {
"description": "Reference to the trained model used for this simulation",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"ScenarioStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Scenariostartdate",
"description": "Start date for scenario comparison period"
},
"ScenarioEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Scenarioenddate",
"description": "End date for scenario comparison period"
},
"UpdateVariable": {
"items": {
"properties": {
"Variable": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"Slug": {
"type": "string",
"title": "Slug"
},
"Type": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes",
"description": "Varaible Tyeps."
},
"Group": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups",
"description": "Vraible groups."
}
},
"type": "object",
"required": [
"IId",
"Name",
"Slug",
"Type",
"Group"
],
"title": "VariableRef",
"description": "Variable reference."
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Value": {
"type": "number",
"title": "Value"
},
"IsScenario": {
"type": "boolean",
"title": "Isscenario"
}
},
"type": "object",
"required": [
"Variable",
"Date",
"Value",
"IsScenario"
],
"title": "SimulationUpdateVariable",
"description": "Updated variables for simulation jobs."
},
"type": "array",
"title": "Updatevariable",
"description": "Variable modifications per scenario (baseline vs scenario values)"
},
"AdditionalConfig": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Additionalconfig",
"description": "Additional simulation configuration parameters"
},
"Seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Seed used for reproducible runs"
},
"AttributionAssociation": {
"items": {
"properties": {
"Attribution": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
},
"Scenario": {
"type": "string",
"title": "Scenario"
},
"Quantile": {
"type": "number",
"title": "Quantile"
}
},
"type": "object",
"required": [
"Attribution",
"Scenario",
"Quantile"
],
"title": "SimulationAttributionAssociation",
"description": "Reference schema for simulation attribution association."
},
"type": "array",
"title": "Attributionassociation",
"description": "Attribution jobs linked to this simulation"
},
"OptimizationJob": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"type": "integer",
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
}
},
"type": "object",
"required": [
"IId",
"JobId",
"Status"
],
"title": "OptimizationJobsRef",
"description": "Reference schema for optimization job."
},
{
"type": "null"
}
],
"description": "Optimization job that created this simulation (if applicable)"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Date",
"Model",
"UpdateVariable",
"AttributionAssociation"
],
"title": "DetailedSimulationJobs",
"description": "Detailed response schema for simulation jobs with scenario configurations.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 456,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Q4 Sales Simulation",
"Note": "Simulation for Q4 marketing scenarios",
"Status": "completed",
"UIFilterAttributionAssociation": [],
"UpdateVariable": []
}
]
}
}
}
},
"404": {
"description": "Simulation job not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Simulation (/api/simulations/update_simulation_projects__team_id___project_id__simulations__simulation_id__patch)
Update metadata attributes of a simulation job.
Allows modification of mutable fields like Name and Note. Cannot modify
computational parameters or scenario configurations after job creation.
Response:
Updated simulation job object with all current attributes.
## PATCH /api/projects/{team_id}/{project_id}/simulations/{simulation_id}
Update Simulation
Update metadata attributes of a simulation job.
Allows modification of mutable fields like Name and Note. Cannot modify
computational parameters or scenario configurations after job creation.
Response:
Updated simulation job object with all current attributes.
```json
{
"tags": [
"Simulations"
],
"summary": "Update Simulation",
"description": "Update metadata attributes of a simulation job.\n\nAllows modification of mutable fields like Name and Note. Cannot modify\ncomputational parameters or scenario configurations after job creation.\n\nResponse:\n Updated simulation job object with all current attributes.",
"operationId": "update_simulation_projects__team_id___project_id__simulations__simulation_id__patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "simulation_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide simulation IId",
"title": "Simulation Id"
},
"description": "Provide simulation IId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Description for the model/dataset"
}
},
"type": "object",
"title": "PatchSimulationJobs",
"description": "Schema for updating simulation jobs.",
"examples": [
{
"Name": "Updated Simulation Name",
"Note": "Simulation job description updated"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"Model": {
"description": "Reference to the trained model used for this simulation",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"ScenarioStartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Scenariostartdate",
"description": "Start date for scenario comparison period"
},
"ScenarioEndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Scenarioenddate",
"description": "End date for scenario comparison period"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Date",
"Model"
],
"title": "SimulationJobs",
"description": "Response schema for simulation jobs listing and summary views.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 456,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Q4 Sales Simulation",
"Note": "Simulation for Q4 marketing scenarios",
"ScenarioEndDate": "2024-12-31T00:00:00",
"ScenarioStartDate": "2024-01-01T00:00:00",
"Status": "completed"
}
]
}
}
}
},
"404": {
"description": "Simulation job not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Simulation (/api/simulations/delete_simulation_projects__team_id___project_id__simulations__simulation_id__delete)
Delete a simulation job and its associated data.
Marks the simulation job for deletion and triggers background cleanup.
The deletion is asynchronous - the job is immediately hidden from
listings but data cleanup happens in the background.
Path Parameters:
- simulation_id: The IId of the simulation job to delete
Response:
- success: Boolean indicating deletion was initiated
- message: Confirmation with the deleted job's IId
Notes:
- Deletion is permanent and cannot be undone
- Associated attribution jobs linked to this simulation are also deleted
- Results data is purged from storage
## DELETE /api/projects/{team_id}/{project_id}/simulations/{simulation_id}
Delete Simulation
Delete a simulation job and its associated data.
Marks the simulation job for deletion and triggers background cleanup.
The deletion is asynchronous - the job is immediately hidden from
listings but data cleanup happens in the background.
Path Parameters:
- simulation_id: The IId of the simulation job to delete
Response:
- success: Boolean indicating deletion was initiated
- message: Confirmation with the deleted job's IId
Notes:
- Deletion is permanent and cannot be undone
- Associated attribution jobs linked to this simulation are also deleted
- Results data is purged from storage
```json
{
"tags": [
"Simulations"
],
"summary": "Delete Simulation",
"description": "Delete a simulation job and its associated data.\n\nMarks the simulation job for deletion and triggers background cleanup.\nThe deletion is asynchronous - the job is immediately hidden from\nlistings but data cleanup happens in the background.\n\nPath Parameters:\n - simulation_id: The IId of the simulation job to delete\n\nResponse:\n - success: Boolean indicating deletion was initiated\n - message: Confirmation with the deleted job's IId\n\nNotes:\n - Deletion is permanent and cannot be undone\n - Associated attribution jobs linked to this simulation are also deleted\n - Results data is purged from storage",
"operationId": "delete_simulation_projects__team_id___project_id__simulations__simulation_id__delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "simulation_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide simulation IId",
"title": "Simulation Id"
},
"description": "Provide simulation IId"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Simulation job not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Simulation Dates Min Max (/api/simulations/get_simulation_dates_min_max_projects__team_id___project_id__simulations__simulation_id__dates_min_max_get)
Get min and max dates from simulation result data.
## GET /api/projects/{team_id}/{project_id}/simulations/{simulation_id}/dates_min_max
Get Simulation Dates Min Max
Get min and max dates from simulation result data.
```json
{
"tags": [
"Simulations"
],
"summary": "Get Simulation Dates Min Max",
"description": "Get min and max dates from simulation result data.",
"operationId": "get_simulation_dates_min_max_projects__team_id___project_id__simulations__simulation_id__dates_min_max_get",
"parameters": [
{
"name": "simulation_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide simulation IId",
"title": "Simulation Id"
},
"description": "Provide simulation IId"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"min": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Min"
},
"max": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Max"
}
},
"type": "object",
"required": [
"min",
"max"
],
"title": "DateRange",
"description": "Min and max dates for a resource collection."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Simulation (/api/simulations/download_simulation_projects__team_id___project_id__simulations__simulation_id__data_get)
Download simulation results as a CSV file.
Returns comparative forecast data showing baseline vs scenario outcomes.
The CSV contains time-series results with uncertainty quantiles for
each scenario, enabling impact analysis.
Prerequisites:
Job Status must be COMPLETED. Poll GET /simulations/{simulation_id}
until Status is COMPLETED before calling this endpoint.
Path Parameters:
- simulation_id: The IId of the simulation job
Query Parameters:
- result_filters: JSON filter expressions to subset results
Example: '{"Country": [["=", "USA"]], "Type": [["=", "Scenario"]]}'
Response:
CSV file stream with columns:
- Variable: KPI/metric name (slug format)
- Effect: Simulated value
- Quantile: Uncertainty percentile
- Type: "BaseScenario" or "Scenario" (for comparison)
- Date: Forecast date
- Country/Region/Grouping: Geographic dimensions (if applicable)
Related:
- GET /simulations/{simulation_id}: Check job status first
- GET /simulations/{simulation_id}/variables: List available variables
## GET /api/projects/{team_id}/{project_id}/simulations/{simulation_id}/data
Download Simulation
Download simulation results as a CSV file.
Returns comparative forecast data showing baseline vs scenario outcomes.
The CSV contains time-series results with uncertainty quantiles for
each scenario, enabling impact analysis.
Prerequisites:
Job Status must be COMPLETED. Poll GET /simulations/{simulation_id}
until Status is COMPLETED before calling this endpoint.
Path Parameters:
- simulation_id: The IId of the simulation job
Query Parameters:
- result_filters: JSON filter expressions to subset results
Example: '{"Country": [["=", "USA"]], "Type": [["=", "Scenario"]]}'
Response:
CSV file stream with columns:
- Variable: KPI/metric name (slug format)
- Effect: Simulated value
- Quantile: Uncertainty percentile
- Type: "BaseScenario" or "Scenario" (for comparison)
- Date: Forecast date
- Country/Region/Grouping: Geographic dimensions (if applicable)
Related:
- GET /simulations/{simulation_id}: Check job status first
- GET /simulations/{simulation_id}/variables: List available variables
```json
{
"tags": [
"Simulations"
],
"summary": "Download Simulation",
"description": "Download simulation results as a CSV file.\n\nReturns comparative forecast data showing baseline vs scenario outcomes.\nThe CSV contains time-series results with uncertainty quantiles for\neach scenario, enabling impact analysis.\n\nPrerequisites:\n Job Status must be COMPLETED. Poll GET /simulations/{simulation_id}\n until Status is COMPLETED before calling this endpoint.\n\nPath Parameters:\n - simulation_id: The IId of the simulation job\n\nQuery Parameters:\n - result_filters: JSON filter expressions to subset results\n Example: '{\"Country\": [[\"=\", \"USA\"]], \"Type\": [[\"=\", \"Scenario\"]]}'\n\nResponse:\n CSV file stream with columns:\n - Variable: KPI/metric name (slug format)\n - Effect: Simulated value\n - Quantile: Uncertainty percentile\n - Type: \"BaseScenario\" or \"Scenario\" (for comparison)\n - Date: Forecast date\n - Country/Region/Grouping: Geographic dimensions (if applicable)\n\nRelated:\n - GET /simulations/{simulation_id}: Check job status first\n - GET /simulations/{simulation_id}/variables: List available variables",
"operationId": "download_simulation_projects__team_id___project_id__simulations__simulation_id__data_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "simulation_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide simulation IId",
"title": "Simulation Id"
},
"description": "Provide simulation IId"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "result_filters",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "\n Filter the simulation result data rows (not the job metadata).\n\n Examples:\n - By country: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - Multiple: result_filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"sales\"]]}'\n - By quantile: result_filters='{\"Quantile\": [[\"=\", \"50\"]]}'\n - Scenario vs baseline: result_filters='{\"Type\": [[\"=\", \"Scenario\"]]}'\n - Combined: result_filters='{\"Type\": [[\"=\", \"BaseScenario\"]]}'\n ",
"title": "Result Filters"
},
"description": "\n Filter the simulation result data rows (not the job metadata).\n\n Examples:\n - By country: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - Multiple: result_filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"sales\"]]}'\n - By quantile: result_filters='{\"Quantile\": [[\"=\", \"50\"]]}'\n - Scenario vs baseline: result_filters='{\"Type\": [[\"=\", \"Scenario\"]]}'\n - Combined: result_filters='{\"Type\": [[\"=\", \"BaseScenario\"]]}'\n "
},
{
"name": "output_format",
"in": "query",
"required": false,
"schema": {
"enum": [
"csv",
"parquet"
],
"type": "string",
"default": "csv",
"title": "Output Format"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Simulation Query (/api/simulations/download_simulation_query_projects__team_id___project_id__simulations__simulation_id__data_query_post)
Download simulation results — POST variant for large filter payloads.
Accepts the same filters as GET /simulations/{simulation_id}/data but
in the request body, avoiding URL length limits.
## POST /api/projects/{team_id}/{project_id}/simulations/{simulation_id}/data_query
Download Simulation Query
Download simulation results — POST variant for large filter payloads.
Accepts the same filters as GET /simulations/{simulation_id}/data but
in the request body, avoiding URL length limits.
```json
{
"tags": [
"Simulations"
],
"summary": "Download Simulation Query",
"description": "Download simulation results — POST variant for large filter payloads.\n\nAccepts the same filters as GET /simulations/{simulation_id}/data but\nin the request body, avoiding URL length limits.",
"operationId": "download_simulation_query_projects__team_id___project_id__simulations__simulation_id__data_query_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "simulation_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide simulation IId",
"title": "Simulation Id"
},
"description": "Provide simulation IId"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"result_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Result Filters"
},
"output_format": {
"type": "string",
"enum": [
"csv",
"parquet"
],
"title": "Output Format",
"default": "csv"
}
},
"type": "object",
"title": "ResultFiltersBody",
"description": "Request body for _query POST endpoints that filter result data rows."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Predictions (/api/predictions/list_predictions_projects__team_id___project_id__predictions_get)
List all prediction jobs in the project with optional filtering.
Returns a paginated list of prediction jobs, useful for monitoring job
status, finding completed predictions, or auditing forecast history.
Query Parameters:
- filters: JSON filter expressions to narrow results by attributes
like DataSet.Name, Model.Name, Status, or date fields.
Example: '{"Status": [["=", "COMPLETED"]]}'
Response:
Paginated list of prediction jobs.
Related:
- GET /predictions/{prediction_id}: Get full details for a specific job
- POST /predictions: Create a new prediction job
## GET /api/projects/{team_id}/{project_id}/predictions
List Predictions
List all prediction jobs in the project with optional filtering.
Returns a paginated list of prediction jobs, useful for monitoring job
status, finding completed predictions, or auditing forecast history.
Query Parameters:
- filters: JSON filter expressions to narrow results by attributes
like DataSet.Name, Model.Name, Status, or date fields.
Example: '{"Status": [["=", "COMPLETED"]]}'
Response:
Paginated list of prediction jobs.
Related:
- GET /predictions/{prediction_id}: Get full details for a specific job
- POST /predictions: Create a new prediction job
```json
{
"tags": [
"Predictions"
],
"summary": "List Predictions",
"description": "List all prediction jobs in the project with optional filtering.\n\nReturns a paginated list of prediction jobs, useful for monitoring job\nstatus, finding completed predictions, or auditing forecast history.\n\nQuery Parameters:\n - filters: JSON filter expressions to narrow results by attributes\n like DataSet.Name, Model.Name, Status, or date fields.\n Example: '{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n\nResponse:\n Paginated list of prediction jobs.\n\nRelated:\n - GET /predictions/{prediction_id}: Get full details for a specific job\n - POST /predictions: Create a new prediction job",
"operationId": "list_predictions_projects__team_id___project_id__predictions_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Multiple filters create OR logic.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By model ID: filters='{\"Model.IId\": [[\"=\", \"42\"]]}'\n - By date: filters='{\"StartDate\": [[\">=\", \"2024-01-01\"]]}'\n - Recent jobs: filters='{\"Date\": [[\">=\", \"2024-10-01\"]]}'\n - By dataset: filters='{\"DataSet.Name\": [[\"contains\", \"Marketing\"]]}'\n - Exclude failed: filters='{\"Status\": [[\"notin\", \"[\\\"FAILED\\\"]\"]]}'\n - Sort newest first: filters='{\"Date\": [[\"orderby\", \"desc\"]]}'\n - Fuzzy name search: filters='{\"Name\": [[\"similarity\", \"Q4 forecast\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby, similarity\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Multiple filters create OR logic.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By model ID: filters='{\"Model.IId\": [[\"=\", \"42\"]]}'\n - By date: filters='{\"StartDate\": [[\">=\", \"2024-01-01\"]]}'\n - Recent jobs: filters='{\"Date\": [[\">=\", \"2024-10-01\"]]}'\n - By dataset: filters='{\"DataSet.Name\": [[\"contains\", \"Marketing\"]]}'\n - Exclude failed: filters='{\"Status\": [[\"notin\", \"[\\\"FAILED\\\"]\"]]}'\n - Sort newest first: filters='{\"Date\": [[\"orderby\", \"desc\"]]}'\n - Fuzzy name search: filters='{\"Name\": [[\"similarity\", \"Q4 forecast\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby, similarity\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"StartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Startdate",
"description": "Forecast period start date"
},
"EndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Enddate",
"description": "Forecast period end date"
},
"Model": {
"description": "Reference to the trained model used for this prediction",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Fit": {
"type": "boolean",
"title": "Fit",
"description": "Whether this is a fit prediction (ModelFitId is set)",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Date",
"Model",
"Fit"
],
"title": "PredictionJobs",
"description": "Response schema for prediction jobs listing and summary views.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"EndDate": "2024-12-31T00:00:00",
"Fit": false,
"IId": 1,
"JobId": 789,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Q4 Sales Prediction",
"Note": "Prediction for Q4 sales",
"StartDate": "2024-01-01T00:00:00",
"Status": "completed"
}
]
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[PredictionJobs]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Submit Prediction (/api/predictions/submit_prediction_projects__team_id___project_id__predictions_post)
Submit a prediction job to forecast KPIs using trained ML models.
Use this endpoint to generate time-series forecasts for business metrics
(e.g., sales, revenue, churn) based on a trained model. Predictions support
uncertainty quantification via configurable quantiles and can include
scenario-based forecasts with modified input variables.
Workflow:
1. Ensure you have a trained model (see POST /build/model)
2. Optionally specify updated_values to create scenario forecasts
3. Submit prediction with this endpoint
4. Poll GET /predictions/{prediction_id} until Status is COMPLETED
5. Retrieve results via GET /predictions/{prediction_id}/data (CSV format)
Response:
Returns the created prediction job. Poll status until COMPLETED.
Related:
- GET /predictions/{prediction_id}: Poll job status and view details
- GET /predictions/{prediction_id}/data: Download forecast results as CSV
- POST /simulations: Compare baseline vs scenario (use for A/B scenarios)
- POST /build/model: Train a model before running predictions
## POST /api/projects/{team_id}/{project_id}/predictions
Submit Prediction
Submit a prediction job to forecast KPIs using trained ML models.
Use this endpoint to generate time-series forecasts for business metrics
(e.g., sales, revenue, churn) based on a trained model. Predictions support
uncertainty quantification via configurable quantiles and can include
scenario-based forecasts with modified input variables.
Workflow:
1. Ensure you have a trained model (see POST /build/model)
2. Optionally specify updated_values to create scenario forecasts
3. Submit prediction with this endpoint
4. Poll GET /predictions/{prediction_id} until Status is COMPLETED
5. Retrieve results via GET /predictions/{prediction_id}/data (CSV format)
Response:
Returns the created prediction job. Poll status until COMPLETED.
Related:
- GET /predictions/{prediction_id}: Poll job status and view details
- GET /predictions/{prediction_id}/data: Download forecast results as CSV
- POST /simulations: Compare baseline vs scenario (use for A/B scenarios)
- POST /build/model: Train a model before running predictions
```json
{
"tags": [
"Predictions"
],
"summary": "Submit Prediction",
"description": "Submit a prediction job to forecast KPIs using trained ML models.\n\nUse this endpoint to generate time-series forecasts for business metrics\n(e.g., sales, revenue, churn) based on a trained model. Predictions support\nuncertainty quantification via configurable quantiles and can include\nscenario-based forecasts with modified input variables.\n\nWorkflow:\n 1. Ensure you have a trained model (see POST /build/model)\n 2. Optionally specify updated_values to create scenario forecasts\n 3. Submit prediction with this endpoint\n 4. Poll GET /predictions/{prediction_id} until Status is COMPLETED\n 5. Retrieve results via GET /predictions/{prediction_id}/data (CSV format)\n\nResponse:\n Returns the created prediction job. Poll status until COMPLETED.\n\nRelated:\n - GET /predictions/{prediction_id}: Poll job status and view details\n - GET /predictions/{prediction_id}/data: Download forecast results as CSV\n - POST /simulations: Compare baseline vs scenario (use for A/B scenarios)\n - POST /build/model: Train a model before running predictions",
"operationId": "submit_prediction_projects__team_id___project_id__predictions_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"model_param": {
"anyOf": [
{
"properties": {
"samples": {
"type": "integer",
"title": "The samples",
"description": "Number of posterior samples to draw for uncertainty estimation. Higher values (e.g., 50-100) give smoother uncertainty bands but take longer. Default (20) is suitable for most use cases.",
"default": 20
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "Job queue priority from 1-100. Higher values are processed first. Use higher priority for time-sensitive predictions. Default (60) is standard priority.",
"default": 60
}
},
"type": "object",
"title": "PredictionParams",
"description": "Sampling and job parameters for prediction execution.",
"examples": [
{
"priority": 60,
"samples": 20
}
]
},
{
"type": "null"
}
],
"description": "Sampling parameters controlling uncertainty estimation. 'samples' determines posterior draws (more = better uncertainty, slower). 'priority' sets job queue priority (higher = processed sooner).",
"default": {
"samples": 20,
"priority": 60
}
},
"prediction_detail": {
"description": "Core prediction configuration: model to use, forecast date range, and dataset reference. Required fields: model_id, start_date, end_date (unless full_prediction=True).",
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Start Date",
"description": "Start of the forecast period. Use ISO 8601 format (e.g., '2024-01-01T00:00:00'). Required unless full_prediction=True. Must align with project periodicity."
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "End Date",
"description": "End of the forecast period. Use ISO 8601 format. Required unless full_prediction=True. Must be after start_date and align with periodicity."
},
"model_id": {
"type": "integer",
"title": "Model Id",
"description": "IId of the trained model to use. Model must have Status=COMPLETED. Get available models from GET /models endpoint."
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Dataset IId to use. Omit or pass 'active' for the project's active dataset. Dataset must be compatible with the model's variables."
},
"full_prediction": {
"type": "boolean",
"title": "Full Prediction",
"description": "If True, creates a prediction covering the model's full training date range. Only one full prediction allowed per model. Ignores start_date and end_date when True.",
"default": false
},
"additional_config": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Additional Config",
"description": "UI-specific configuration passed through to frontend display."
}
},
"type": "object",
"required": [
"model_id"
],
"title": "PredictionDetail",
"examples": [
{
"dataset_id": "active",
"end_date": "2024-12-31T00:00:00",
"full_prediction": false,
"model_id": 1,
"name": "Q4 Sales Prediction",
"note": "Forecast sales based on planned media spend",
"start_date": "2024-01-01T00:00:00"
}
]
},
"updated_values": {
"additionalProperties": {
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable"
},
"update": {
"anyOf": [
{
"items": {
"prefixItems": [
{
"type": "string",
"format": "date-time",
"title": "Date"
},
{
"type": "number",
"title": "Value"
}
],
"type": "array",
"maxItems": 2,
"minItems": 2
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Update"
}
},
"type": "object",
"required": [
"variable",
"update"
],
"title": "UpdatedVariable",
"description": "Schema for schenario updated variabls values."
},
"type": "array"
},
"type": "object",
"title": "Updated Values",
"description": "Scenario variable modifications. Dict with scenario names as keys (e.g., 'Scenario'), each containing list of {variable, update}. Defaults to a single empty 'Scenario' (identical to baseline)."
},
"quantiles": {
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array",
"title": "Quantiles",
"description": "Uncertainty percentiles to compute (1-100). Output includes forecast values at each quantile. Common: [20, 40, 50, 60, 80] for median + ranges.",
"default": [
20,
40,
50,
60,
80
]
},
"target_nodes": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Target Nodes",
"description": "Specific KPI variable slugs to forecast. If None, predicts all target nodes in the model graph. Use to reduce output size when only specific KPIs are needed."
},
"freeze_nodes": {
"anyOf": [
{
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Freeze Nodes",
"description": "Variables to freeze at their data values instead of predicting. Dict mapping scenario names to lists of variable slugs. Advanced feature for partial forecasting."
},
"attributions": {
"items": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"samples": {
"type": "integer",
"title": "The samples",
"description": "Hom many subsamples to draw from the posterior distribution. The higher number of samples the better the uncertainty estimation becomes but it also takes longer to run.",
"default": 20
},
"baseline": {
"anyOf": [
{
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable",
"description": "Variable slug."
},
"baseline": {
"type": "number",
"title": "Baseline",
"description": "Set baseline."
}
},
"type": "object",
"required": [
"variable",
"baseline"
],
"title": "ReferencePointBaseline",
"description": "Attribution job baseline."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Baseline"
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
},
"quantiles": {
"anyOf": [
{
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Quantiles",
"default": [
1,
25,
50,
75,
99
]
},
"referece_point_fallback": {
"anyOf": [
{
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback",
"description": "Attribution's reference point fallback."
},
{
"type": "null"
}
],
"description": "Reference point fallback.",
"default": "Min"
},
"predicted_targets_as_data": {
"type": "boolean",
"title": "Predicted Targets As Data",
"description": "Set predicted targets as data.",
"default": true
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Optional integer seed. If omitted, the chained attribution inherits the parent job's seed."
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Start Date",
"description": "The first date in the date range used to select data from the dataset"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "End Date",
"description": "The last date in the date range used to select data from the dataset."
},
"prediction_quantile": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "Prediction Quantile",
"description": "Prediction quantile to run attribution.",
"default": 50
},
"prediction_scenario": {
"type": "string",
"title": "Prediction Scenario",
"description": "Prediction scenario to run attribution.",
"default": "Scenario"
}
},
"type": "object",
"title": "PredictionAttribution",
"description": "Run attribution after prediction job."
},
"type": "array",
"title": "Attributions",
"description": "Optional attribution jobs to auto-create after prediction completes. Use to analyze which input variables drove the forecast outcomes."
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Optional integer seed for reproducible runs. If omitted, the server generates a random seed."
},
"validate_limits": {
"type": "boolean",
"title": "Validate Limits",
"description": "Validate values against per-variable min/max limits.",
"default": false
}
},
"type": "object",
"required": [
"prediction_detail"
],
"title": "PredictionRequest",
"description": "Request body for creating a prediction job to forecast KPIs.",
"examples": [
{
"attributions": [
{
"name": "Prediction Attribution",
"prediction_quantile": 50,
"prediction_scenario": "Scenario",
"priority": 30,
"quantiles": [
1,
25,
50,
75,
99
],
"samples": 20
}
],
"model_param": {
"priority": 60,
"samples": 20
},
"prediction_detail": {
"dataset_id": "active",
"end_date": "2024-12-31T00:00:00",
"full_prediction": false,
"model_id": 1,
"name": "Q4 Sales Prediction",
"note": "Forecast for Q4 with planned media spend",
"start_date": "2024-01-01T00:00:00"
},
"quantiles": [
20,
40,
50,
60,
80
],
"updated_values": {
"Scenario": [
{
"update": [
[
"2024-01-01",
15000
],
[
"2024-06-01",
15000
],
[
"2024-12-01",
15000
]
],
"variable": "tv_spend"
},
{
"update": [
[
"2024-01-01",
7500
],
[
"2024-06-01",
7500
],
[
"2024-12-01",
7500
]
],
"variable": "digital_spend"
}
]
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"StartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Startdate",
"description": "Forecast period start date"
},
"EndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Enddate",
"description": "Forecast period end date"
},
"Model": {
"description": "Reference to the trained model used for this prediction",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Fit": {
"type": "boolean",
"title": "Fit",
"description": "Whether this is a fit prediction (ModelFitId is set)",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Date",
"Model",
"Fit"
],
"title": "PredictionJobs",
"description": "Response schema for prediction jobs listing and summary views.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"EndDate": "2024-12-31T00:00:00",
"Fit": false,
"IId": 1,
"JobId": 789,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Q4 Sales Prediction",
"Note": "Prediction for Q4 sales",
"StartDate": "2024-01-01T00:00:00",
"Status": "completed"
}
]
}
}
}
},
"400": {
"description": "Invalid prediction request: model not found, invalid date range, quantile out of range (1-100), or dataset incompatible with model variables",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Project is in read-only state",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Bulk Delete Predictions (/api/predictions/bulk_delete_predictions_projects__team_id___project_id__predictions_delete)
Bulk delete prediction jobs matching the given filters.
Marks all matching jobs for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
## DELETE /api/projects/{team_id}/{project_id}/predictions
Bulk Delete Predictions
Bulk delete prediction jobs matching the given filters.
Marks all matching jobs for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
```json
{
"tags": [
"Predictions"
],
"summary": "Bulk Delete Predictions",
"description": "Bulk delete prediction jobs matching the given filters.\n\nMarks all matching jobs for deletion and publishes delete messages to\nRabbitMQ concurrently in the background via a single DB round-trip each.",
"operationId": "bulk_delete_predictions_projects__team_id___project_id__predictions_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /predictions.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By date: filters='{\"Date\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /predictions.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By date: filters='{\"Date\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n "
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Prediction (/api/predictions/get_prediction_projects__team_id___project_id__predictions__prediction_id__get)
Get detailed information about a specific prediction job.
Use this endpoint to check job status, view configuration parameters,
and access metadata. Poll this endpoint until Status is COMPLETED
before downloading results.
Path Parameters:
- prediction_id: The IId of the prediction job to retrieve
Response:
Detailed prediction job object with scenario configurations and task progress.
Related:
- GET /predictions/{prediction_id}/data: Download results (after COMPLETED)
- DELETE /predictions/{prediction_id}: Remove the prediction job
## GET /api/projects/{team_id}/{project_id}/predictions/{prediction_id}
Get Prediction
Get detailed information about a specific prediction job.
Use this endpoint to check job status, view configuration parameters,
and access metadata. Poll this endpoint until Status is COMPLETED
before downloading results.
Path Parameters:
- prediction_id: The IId of the prediction job to retrieve
Response:
Detailed prediction job object with scenario configurations and task progress.
Related:
- GET /predictions/{prediction_id}/data: Download results (after COMPLETED)
- DELETE /predictions/{prediction_id}: Remove the prediction job
```json
{
"tags": [
"Predictions"
],
"summary": "Get Prediction",
"description": "Get detailed information about a specific prediction job.\n\nUse this endpoint to check job status, view configuration parameters,\nand access metadata. Poll this endpoint until Status is COMPLETED\nbefore downloading results.\n\nPath Parameters:\n - prediction_id: The IId of the prediction job to retrieve\n\nResponse:\n Detailed prediction job object with scenario configurations and task progress.\n\nRelated:\n - GET /predictions/{prediction_id}/data: Download results (after COMPLETED)\n - DELETE /predictions/{prediction_id}: Remove the prediction job",
"operationId": "get_prediction_projects__team_id___project_id__predictions__prediction_id__get",
"parameters": [
{
"name": "prediction_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide prediction IId",
"title": "Prediction Id"
},
"description": "Provide prediction IId"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"Task": {
"anyOf": [
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"Topic": {
"type": "string",
"enum": [
"ATTRIBUTIONSET",
"ATTRIBUTIONJOB",
"SIMULATIONJOB",
"PREDICTIONJOB",
"TRAINJOB",
"DATASET",
"DATAUPLOAD",
"GRAPHCONSTRUCT",
"GENERAL",
"OPTIMIZATIONJOB",
"RESPOSNSECURVEJOB",
"PRIORPOSTERIORJOB",
"EXCELJOB",
"GRAPHBASIC",
"FEATUREIMPORTANCE",
"GRAPHSYNERGY"
],
"title": "TaskTopics",
"description": "Task topics."
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"Id",
"Config",
"Topic",
"Status"
],
"title": "Task",
"description": "Reference task."
},
{
"type": "null"
}
]
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"StartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Startdate",
"description": "Forecast period start date"
},
"EndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Enddate",
"description": "Forecast period end date"
},
"Model": {
"description": "Reference to the trained model used for this prediction",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Scenarios": {
"items": {
"properties": {
"Name": {
"type": "string",
"title": "Name"
},
"UpdateVariable": {
"items": {
"properties": {
"Variable": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"Slug": {
"type": "string",
"title": "Slug"
},
"Type": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes",
"description": "Varaible Tyeps."
},
"Group": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups",
"description": "Vraible groups."
}
},
"type": "object",
"required": [
"IId",
"Name",
"Slug",
"Type",
"Group"
],
"title": "VariableRef",
"description": "Variable reference."
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Value": {
"type": "number",
"title": "Value"
}
},
"type": "object",
"required": [
"Variable",
"Date",
"Value"
],
"title": "UpdateVariable",
"description": "Updated variables."
},
"type": "array",
"title": "Updatevariable"
}
},
"type": "object",
"required": [
"Name",
"UpdateVariable"
],
"title": "_DetailedPredictionScenarios"
},
"type": "array",
"title": "Scenarios",
"description": "Named scenarios with variable modifications"
},
"AdditionalConfig": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Additionalconfig",
"description": "Additional prediction configuration parameters"
},
"Seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Seed used for reproducible runs"
},
"AttributionAssociation": {
"items": {
"properties": {
"Attribution": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
},
"Scenario": {
"type": "string",
"title": "Scenario"
},
"Quantile": {
"type": "number",
"title": "Quantile"
}
},
"type": "object",
"required": [
"Attribution",
"Scenario",
"Quantile"
],
"title": "PredictionAttributionAssociation",
"description": "Reference schema for prediction attribution association."
},
"type": "array",
"title": "Attributionassociation",
"description": "Attribution jobs linked to this prediction"
},
"FullModel": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
},
{
"type": "null"
}
],
"description": "Model used for full-period prediction"
},
"FreezeNodes": {
"anyOf": [
{
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Freezenodes",
"description": "Variables frozen to data values during prediction"
},
"Quantiles": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Quantiles",
"description": "Uncertainty quantiles computed (e.g., [5, 50, 95])"
},
"TargetNodes": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Targetnodes",
"description": "Target variables being predicted"
},
"Fit": {
"type": "boolean",
"title": "Fit",
"description": "Whether this is a fit prediction (ModelFitId is set)",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Date",
"Model",
"Scenarios",
"AttributionAssociation",
"Fit"
],
"title": "DetailedPredictionJobs",
"description": "Detailed response schema for prediction jobs with scenarios and configuration.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 789,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Q4 Sales Prediction",
"Note": "Prediction for Q4 sales",
"Scenarios": [],
"Status": "completed",
"UIFilterAttributionAssociation": []
}
]
}
}
}
},
"404": {
"description": "Prediction job not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Prediction (/api/predictions/update_prediction_projects__team_id___project_id__predictions__prediction_id__patch)
Update metadata attributes of a prediction job.
Allows modification of mutable fields like Name and Note. Cannot modify
computational parameters or results after job creation.
Response:
Updated prediction job object with all current attributes.
## PATCH /api/projects/{team_id}/{project_id}/predictions/{prediction_id}
Update Prediction
Update metadata attributes of a prediction job.
Allows modification of mutable fields like Name and Note. Cannot modify
computational parameters or results after job creation.
Response:
Updated prediction job object with all current attributes.
```json
{
"tags": [
"Predictions"
],
"summary": "Update Prediction",
"description": "Update metadata attributes of a prediction job.\n\nAllows modification of mutable fields like Name and Note. Cannot modify\ncomputational parameters or results after job creation.\n\nResponse:\n Updated prediction job object with all current attributes.",
"operationId": "update_prediction_projects__team_id___project_id__predictions__prediction_id__patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "prediction_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide prediction IId",
"title": "Prediction Id"
},
"description": "Provide prediction IId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Description for the model/dataset"
}
},
"type": "object",
"title": "PatchPredictionJobs",
"description": "Schema for updating prediction jobs.",
"examples": [
{
"Name": "Updated Prediction Name",
"Note": "Prediction job description updated"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"StartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Startdate",
"description": "Forecast period start date"
},
"EndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Enddate",
"description": "Forecast period end date"
},
"Model": {
"description": "Reference to the trained model used for this prediction",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Fit": {
"type": "boolean",
"title": "Fit",
"description": "Whether this is a fit prediction (ModelFitId is set)",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Date",
"Model",
"Fit"
],
"title": "PredictionJobs",
"description": "Response schema for prediction jobs listing and summary views.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"EndDate": "2024-12-31T00:00:00",
"Fit": false,
"IId": 1,
"JobId": 789,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Q4 Sales Prediction",
"Note": "Prediction for Q4 sales",
"StartDate": "2024-01-01T00:00:00",
"Status": "completed"
}
]
}
}
}
},
"404": {
"description": "Prediction job not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Prediction (/api/predictions/delete_prediction_projects__team_id___project_id__predictions__prediction_id__delete)
Delete a prediction job and its associated data.
Marks the prediction job for deletion and triggers background cleanup
of all associated resources (results, attributions). The deletion is
asynchronous - the job is immediately hidden from listings but data
cleanup happens in the background.
Path Parameters:
- prediction_id: The IId of the prediction job to delete
Response:
- success: Boolean indicating deletion was initiated
- message: Confirmation with the deleted job's IId
Notes:
- Deletion is permanent and cannot be undone
- Associated attribution jobs linked to this prediction are also deleted
- Results data is purged from storage
## DELETE /api/projects/{team_id}/{project_id}/predictions/{prediction_id}
Delete Prediction
Delete a prediction job and its associated data.
Marks the prediction job for deletion and triggers background cleanup
of all associated resources (results, attributions). The deletion is
asynchronous - the job is immediately hidden from listings but data
cleanup happens in the background.
Path Parameters:
- prediction_id: The IId of the prediction job to delete
Response:
- success: Boolean indicating deletion was initiated
- message: Confirmation with the deleted job's IId
Notes:
- Deletion is permanent and cannot be undone
- Associated attribution jobs linked to this prediction are also deleted
- Results data is purged from storage
```json
{
"tags": [
"Predictions"
],
"summary": "Delete Prediction",
"description": "Delete a prediction job and its associated data.\n\nMarks the prediction job for deletion and triggers background cleanup\nof all associated resources (results, attributions). The deletion is\nasynchronous - the job is immediately hidden from listings but data\ncleanup happens in the background.\n\nPath Parameters:\n - prediction_id: The IId of the prediction job to delete\n\nResponse:\n - success: Boolean indicating deletion was initiated\n - message: Confirmation with the deleted job's IId\n\nNotes:\n - Deletion is permanent and cannot be undone\n - Associated attribution jobs linked to this prediction are also deleted\n - Results data is purged from storage",
"operationId": "delete_prediction_projects__team_id___project_id__predictions__prediction_id__delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "prediction_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide prediction IId",
"title": "Prediction Id"
},
"description": "Provide prediction IId"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Prediction job not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Prediction Dates Min Max (/api/predictions/get_prediction_dates_min_max_projects__team_id___project_id__predictions__prediction_id__dates_min_max_get)
Get min and max dates from prediction result data.
## GET /api/projects/{team_id}/{project_id}/predictions/{prediction_id}/dates_min_max
Get Prediction Dates Min Max
Get min and max dates from prediction result data.
```json
{
"tags": [
"Predictions"
],
"summary": "Get Prediction Dates Min Max",
"description": "Get min and max dates from prediction result data.",
"operationId": "get_prediction_dates_min_max_projects__team_id___project_id__predictions__prediction_id__dates_min_max_get",
"parameters": [
{
"name": "prediction_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide prediction IId",
"title": "Prediction Id"
},
"description": "Provide prediction IId"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"min": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Min"
},
"max": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Max"
}
},
"type": "object",
"required": [
"min",
"max"
],
"title": "DateRange",
"description": "Min and max dates for a resource collection."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Prediction (/api/predictions/download_prediction_projects__team_id___project_id__predictions__prediction_id__data_get)
Download prediction results as a CSV file.
Returns forecast data for a completed prediction job. The CSV contains
time-series forecasts with uncertainty quantiles for each variable
in the model's output.
Prerequisites:
Job Status must be COMPLETED. Poll GET /predictions/{prediction_id}
until Status is COMPLETED before calling this endpoint.
Path Parameters:
- prediction_id: The IId of the prediction job
Query Parameters:
- result_filters: JSON filter expressions to subset results
Example: '{"Country": [["=", "USA"]], "Variable": [["contains", "sales"]]}'
Response:
CSV file stream with columns:
- Variable: KPI/metric name (slug format)
- Effect: Predicted value
- Quantile: Uncertainty percentile (matches requested quantiles)
- Scenario: Scenario name (from updated_values)
- Date: Forecast date
- Country/Region/Grouping: Geographic dimensions (if applicable)
Related:
- GET /predictions/{prediction_id}: Check job status first
- GET /predictions/{prediction_id}/variables: List available variables
## GET /api/projects/{team_id}/{project_id}/predictions/{prediction_id}/data
Download Prediction
Download prediction results as a CSV file.
Returns forecast data for a completed prediction job. The CSV contains
time-series forecasts with uncertainty quantiles for each variable
in the model's output.
Prerequisites:
Job Status must be COMPLETED. Poll GET /predictions/{prediction_id}
until Status is COMPLETED before calling this endpoint.
Path Parameters:
- prediction_id: The IId of the prediction job
Query Parameters:
- result_filters: JSON filter expressions to subset results
Example: '{"Country": [["=", "USA"]], "Variable": [["contains", "sales"]]}'
Response:
CSV file stream with columns:
- Variable: KPI/metric name (slug format)
- Effect: Predicted value
- Quantile: Uncertainty percentile (matches requested quantiles)
- Scenario: Scenario name (from updated_values)
- Date: Forecast date
- Country/Region/Grouping: Geographic dimensions (if applicable)
Related:
- GET /predictions/{prediction_id}: Check job status first
- GET /predictions/{prediction_id}/variables: List available variables
```json
{
"tags": [
"Predictions"
],
"summary": "Download Prediction",
"description": "Download prediction results as a CSV file.\n\nReturns forecast data for a completed prediction job. The CSV contains\ntime-series forecasts with uncertainty quantiles for each variable\nin the model's output.\n\nPrerequisites:\n Job Status must be COMPLETED. Poll GET /predictions/{prediction_id}\n until Status is COMPLETED before calling this endpoint.\n\nPath Parameters:\n - prediction_id: The IId of the prediction job\n\nQuery Parameters:\n - result_filters: JSON filter expressions to subset results\n Example: '{\"Country\": [[\"=\", \"USA\"]], \"Variable\": [[\"contains\", \"sales\"]]}'\n\nResponse:\n CSV file stream with columns:\n - Variable: KPI/metric name (slug format)\n - Effect: Predicted value\n - Quantile: Uncertainty percentile (matches requested quantiles)\n - Scenario: Scenario name (from updated_values)\n - Date: Forecast date\n - Country/Region/Grouping: Geographic dimensions (if applicable)\n\nRelated:\n - GET /predictions/{prediction_id}: Check job status first\n - GET /predictions/{prediction_id}/variables: List available variables",
"operationId": "download_prediction_projects__team_id___project_id__predictions__prediction_id__data_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "prediction_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide prediction IId",
"title": "Prediction Id"
},
"description": "Provide prediction IId"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "result_filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n Filter the prediction result data rows (not the job metadata).\n\n Examples:\n - By country: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - Multiple: result_filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"sales\"]]}'\n - By quantile: result_filters='{\"Quantile\": [[\"=\", \"50\"]]}'\n - By scenario: result_filters='{\"Scenario\": [[\"=\", \"Baseline\"]]}'\n - Combined: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n ",
"title": "Result Filters"
},
"description": "\n Filter the prediction result data rows (not the job metadata).\n\n Examples:\n - By country: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - Multiple: result_filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"sales\"]]}'\n - By quantile: result_filters='{\"Quantile\": [[\"=\", \"50\"]]}'\n - By scenario: result_filters='{\"Scenario\": [[\"=\", \"Baseline\"]]}'\n - Combined: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n "
},
{
"name": "output_format",
"in": "query",
"required": false,
"schema": {
"enum": [
"csv",
"parquet"
],
"type": "string",
"default": "csv",
"title": "Output Format"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Prediction Query (/api/predictions/download_prediction_query_projects__team_id___project_id__predictions__prediction_id__data_query_post)
Download prediction results — POST variant for large filter payloads.
Accepts the same filters as GET /predictions/{prediction_id}/data but
in the request body, avoiding URL length limits.
## POST /api/projects/{team_id}/{project_id}/predictions/{prediction_id}/data_query
Download Prediction Query
Download prediction results — POST variant for large filter payloads.
Accepts the same filters as GET /predictions/{prediction_id}/data but
in the request body, avoiding URL length limits.
```json
{
"tags": [
"Predictions"
],
"summary": "Download Prediction Query",
"description": "Download prediction results — POST variant for large filter payloads.\n\nAccepts the same filters as GET /predictions/{prediction_id}/data but\nin the request body, avoiding URL length limits.",
"operationId": "download_prediction_query_projects__team_id___project_id__predictions__prediction_id__data_query_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "prediction_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide prediction IId",
"title": "Prediction Id"
},
"description": "Provide prediction IId"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"result_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Result Filters"
},
"minimize_format": {
"type": "boolean",
"title": "Minimize Format",
"default": false
},
"output_format": {
"type": "string",
"enum": [
"csv",
"parquet"
],
"title": "Output Format",
"default": "csv"
}
},
"type": "object",
"title": "DownloadPredictionBody",
"description": "Request body for prediction download _query endpoint."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Attributions (/api/attributions/list_attributions_projects__team_id___project_id__attributions_get)
List attributions.
Retrieves a paginated list of attribution jobs that analyze variable
impacts within a project, with optional filters like model name.
## GET /api/projects/{team_id}/{project_id}/attributions
List Attributions
List attributions.
Retrieves a paginated list of attribution jobs that analyze variable
impacts within a project, with optional filters like model name.
```json
{
"tags": [
"Attributions"
],
"summary": "List Attributions",
"description": "List attributions.\n\nRetrieves a paginated list of attribution jobs that analyze variable\nimpacts within a project, with optional filters like model name.",
"operationId": "list_attributions_projects__team_id___project_id__attributions_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Multiple filters create OR logic.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By model ID: filters='{\"Model.IId\": [[\"=\", \"42\"]]}'\n - Recent jobs: filters='{\"Date\": [[\">=\", \"2024-10-01\"]]}'\n - By dataset: filters='{\"DataSet.Name\": [[\"contains\", \"Marketing\"]]}'\n - Sort by date: filters='{\"Date\": [[\"orderby\", \"desc\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Multiple filters create OR logic.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By model ID: filters='{\"Model.IId\": [[\"=\", \"42\"]]}'\n - Recent jobs: filters='{\"Date\": [[\">=\", \"2024-10-01\"]]}'\n - By dataset: filters='{\"DataSet.Name\": [[\"contains\", \"Marketing\"]]}'\n - Sort by date: filters='{\"Date\": [[\"orderby\", \"desc\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Model": {
"description": "Reference to the trained model used for attribution",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"Fit": {
"type": "boolean",
"title": "Fit",
"description": "Whether this is a fit attribution (FitModelId is set)",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Model",
"Date",
"Fit"
],
"title": "Attribution",
"description": "Response schema for attribution analysis jobs.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00Z",
"Fit": false,
"IId": 1,
"JobId": 123,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "Marketing Model",
"Region": "all"
},
"Name": "Q4 Attribution Analysis",
"Note": "Attribution analysis for Q4 marketing data",
"Status": "completed"
}
]
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[Attribution]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Submit Attribution (/api/attributions/submit_attribution_projects__team_id___project_id__attributions_post)
Submit an attribution job.
This endpoint submits an attribution job based on the provided request data.
## POST /api/projects/{team_id}/{project_id}/attributions
Submit Attribution
Submit an attribution job.
This endpoint submits an attribution job based on the provided request data.
```json
{
"tags": [
"Attributions"
],
"summary": "Submit Attribution",
"description": "Submit an attribution job.\n\nThis endpoint submits an attribution job based on the provided request data.",
"operationId": "submit_attribution_projects__team_id___project_id__attributions_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"samples": {
"type": "integer",
"title": "The samples",
"description": "Hom many subsamples to draw from the posterior distribution. The higher number of samples the better the uncertainty estimation becomes but it also takes longer to run.",
"default": 20
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Start Date",
"description": "The first date in the date range used to select data from the dataset"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "End Date",
"description": "The last date in the date range used to select data from the dataset."
},
"baseline": {
"anyOf": [
{
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable",
"description": "Variable slug."
},
"baseline": {
"type": "number",
"title": "Baseline",
"description": "Set baseline."
}
},
"type": "object",
"required": [
"variable",
"baseline"
],
"title": "ReferencePointBaseline",
"description": "Attribution job baseline."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Baseline"
},
"model_id": {
"type": "integer",
"title": "Model Id",
"description": "The id of the model that should be used to do the attribution with."
},
"quantiles": {
"anyOf": [
{
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Quantiles",
"default": [
1,
25,
50,
75,
99
]
},
"predicted_targets_as_data": {
"type": "boolean",
"title": "Predicted Targets As Data",
"default": true
},
"fit_attribution": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Fit Attribution",
"description": "Set attribution as fit attribution of the model.",
"default": false
},
"referece_point_fallback": {
"anyOf": [
{
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback",
"description": "Attribution's reference point fallback."
},
{
"type": "null"
}
],
"description": "Reference point fallback.",
"default": "Min"
},
"updated_values": {
"anyOf": [
{
"additionalProperties": {
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable"
},
"update": {
"anyOf": [
{
"items": {
"prefixItems": [
{
"type": "string",
"format": "date-time",
"title": "Date"
},
{
"type": "number",
"title": "Value"
}
],
"type": "array",
"maxItems": 2,
"minItems": 2
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Update"
}
},
"type": "object",
"required": [
"variable",
"update"
],
"title": "UpdatedVariable",
"description": "Schema for schenario updated variabls values."
},
"type": "array"
},
"propertyNames": {
"const": "scenario"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Updated Values",
"description": "The updated values variable."
},
"job_input": {
"anyOf": [
{
"anyOf": [
{
"properties": {
"id": {
"type": "integer",
"title": "Id"
},
"quantile": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "Quantile"
},
"scenario": {
"type": "string",
"enum": [
"BaseScenario",
"Scenario"
],
"title": "Scenario"
},
"job_type": {
"type": "string",
"const": "simulation",
"title": "Job Type",
"default": "simulation"
}
},
"type": "object",
"required": [
"id",
"quantile",
"scenario"
],
"title": "SimulationAttributionInput",
"description": "Attribution job from simulation result."
},
{
"properties": {
"id": {
"type": "integer",
"title": "Id"
},
"quantile": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "Quantile"
},
"scenario": {
"type": "string",
"title": "Scenario"
},
"job_type": {
"type": "string",
"const": "prediction",
"title": "Job Type",
"default": "prediction"
}
},
"type": "object",
"required": [
"id",
"quantile",
"scenario"
],
"title": "PredictionAttributionInput",
"description": "Attribution job from prediction result."
},
{
"properties": {
"id": {
"type": "integer",
"title": "Id"
},
"job_type": {
"type": "string",
"const": "optimization",
"title": "Job Type",
"default": "optimization"
}
},
"type": "object",
"required": [
"id"
],
"title": "OptimizationAttributionInput",
"description": "Attribution job from optimization result."
}
],
"description": "job_type"
},
{
"type": "null"
}
],
"title": "Job Input",
"description": "Run attribution from other job result."
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Optional integer seed for reproducible runs. If omitted, the server generates a random seed."
},
"auto_activate": {
"type": "boolean",
"title": "Auto Activate",
"description": "If true, automatically creates and activates an attribution set from this job once it completes.",
"default": false
},
"validate_limits": {
"type": "boolean",
"title": "Validate Limits",
"description": "Validate values against per-variable min/max limits.",
"default": false
}
},
"type": "object",
"required": [
"model_id"
],
"title": "AttributionRequest",
"description": "Schemas of attribution request endpoint, samples priority, and model id.",
"examples": [
{
"baseline": [
{
"baseline": 1000,
"variable": "base_sales"
}
],
"dataset_id": "active",
"end_date": "2024-12-31T00:00:00",
"fit_attribution": false,
"model_id": 1,
"name": "USA Market Attribution Q4",
"note": "Attribution analysis for USA market Q4 2024",
"predicted_targets_as_data": true,
"priority": 30,
"quantiles": [
1,
25,
50,
75,
99
],
"referece_point_fallback": "Min",
"samples": 20,
"start_date": "2024-01-01T00:00:00"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Model": {
"description": "Reference to the trained model used for attribution",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"Fit": {
"type": "boolean",
"title": "Fit",
"description": "Whether this is a fit attribution (FitModelId is set)",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Model",
"Date",
"Fit"
],
"title": "Attribution",
"description": "Response schema for attribution analysis jobs.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00Z",
"Fit": false,
"IId": 1,
"JobId": 123,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "Marketing Model",
"Region": "all"
},
"Name": "Q4 Attribution Analysis",
"Note": "Attribution analysis for Q4 marketing data",
"Status": "completed"
}
]
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Bulk Delete Attributions (/api/attributions/bulk_delete_attributions_projects__team_id___project_id__attributions_delete)
Bulk delete attribution jobs matching the given filters.
Marks all matching jobs for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
Attribution jobs used in an active attribution set are excluded.
## DELETE /api/projects/{team_id}/{project_id}/attributions
Bulk Delete Attributions
Bulk delete attribution jobs matching the given filters.
Marks all matching jobs for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
Attribution jobs used in an active attribution set are excluded.
```json
{
"tags": [
"Attributions"
],
"summary": "Bulk Delete Attributions",
"description": "Bulk delete attribution jobs matching the given filters.\n\nMarks all matching jobs for deletion and publishes delete messages to\nRabbitMQ concurrently in the background via a single DB round-trip each.\nAttribution jobs used in an active attribution set are excluded.",
"operationId": "bulk_delete_attributions_projects__team_id___project_id__attributions_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /attributions.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By date: filters='{\"Date\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /attributions.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By date: filters='{\"Date\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n "
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Submit Attribution From Job (/api/attributions/submit_attribution_from_job_projects__team_id___project_id__attributions_from_job_post)
Submit an attribution job using a simulation/prediction/optimization as input.
`job_input` is required. The source job is validated (exists, COMPLETED,
matching modelling_combination, and result rows present in Postgres or S3);
dataset and (for prediction sources) fit model are derived from it.
## POST /api/projects/{team_id}/{project_id}/attributions_from_job
Submit Attribution From Job
Submit an attribution job using a simulation/prediction/optimization as input.
`job_input` is required. The source job is validated (exists, COMPLETED,
matching modelling_combination, and result rows present in Postgres or S3);
dataset and (for prediction sources) fit model are derived from it.
```json
{
"tags": [
"Attributions"
],
"summary": "Submit Attribution From Job",
"description": "Submit an attribution job using a simulation/prediction/optimization as input.\n\n`job_input` is required. The source job is validated (exists, COMPLETED,\nmatching modelling_combination, and result rows present in Postgres or S3);\ndataset and (for prediction sources) fit model are derived from it.",
"operationId": "submit_attribution_from_job_projects__team_id___project_id__attributions_from_job_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"samples": {
"type": "integer",
"title": "The samples",
"description": "Hom many subsamples to draw from the posterior distribution. The higher number of samples the better the uncertainty estimation becomes but it also takes longer to run.",
"default": 20
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Start Date",
"description": "The first date in the date range used to select data from the dataset"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "End Date",
"description": "The last date in the date range used to select data from the dataset."
},
"baseline": {
"anyOf": [
{
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable",
"description": "Variable slug."
},
"baseline": {
"type": "number",
"title": "Baseline",
"description": "Set baseline."
}
},
"type": "object",
"required": [
"variable",
"baseline"
],
"title": "ReferencePointBaseline",
"description": "Attribution job baseline."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Baseline"
},
"model_id": {
"type": "integer",
"title": "Model Id",
"description": "The id of the model that should be used to do the attribution with."
},
"quantiles": {
"anyOf": [
{
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Quantiles",
"default": [
1,
25,
50,
75,
99
]
},
"predicted_targets_as_data": {
"type": "boolean",
"title": "Predicted Targets As Data",
"default": true
},
"fit_attribution": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Fit Attribution",
"description": "Set attribution as fit attribution of the model.",
"default": false
},
"referece_point_fallback": {
"anyOf": [
{
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback",
"description": "Attribution's reference point fallback."
},
{
"type": "null"
}
],
"description": "Reference point fallback.",
"default": "Min"
},
"updated_values": {
"anyOf": [
{
"additionalProperties": {
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable"
},
"update": {
"anyOf": [
{
"items": {
"prefixItems": [
{
"type": "string",
"format": "date-time",
"title": "Date"
},
{
"type": "number",
"title": "Value"
}
],
"type": "array",
"maxItems": 2,
"minItems": 2
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Update"
}
},
"type": "object",
"required": [
"variable",
"update"
],
"title": "UpdatedVariable",
"description": "Schema for schenario updated variabls values."
},
"type": "array"
},
"propertyNames": {
"const": "scenario"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Updated Values",
"description": "The updated values variable."
},
"job_input": {
"anyOf": [
{
"properties": {
"id": {
"type": "integer",
"title": "Id"
},
"quantile": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "Quantile"
},
"scenario": {
"type": "string",
"enum": [
"BaseScenario",
"Scenario"
],
"title": "Scenario"
},
"job_type": {
"type": "string",
"const": "simulation",
"title": "Job Type",
"default": "simulation"
}
},
"type": "object",
"required": [
"id",
"quantile",
"scenario"
],
"title": "SimulationAttributionInput",
"description": "Attribution job from simulation result."
},
{
"properties": {
"id": {
"type": "integer",
"title": "Id"
},
"quantile": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "Quantile"
},
"scenario": {
"type": "string",
"title": "Scenario"
},
"job_type": {
"type": "string",
"const": "prediction",
"title": "Job Type",
"default": "prediction"
}
},
"type": "object",
"required": [
"id",
"quantile",
"scenario"
],
"title": "PredictionAttributionInput",
"description": "Attribution job from prediction result."
},
{
"properties": {
"id": {
"type": "integer",
"title": "Id"
},
"job_type": {
"type": "string",
"const": "optimization",
"title": "Job Type",
"default": "optimization"
}
},
"type": "object",
"required": [
"id"
],
"title": "OptimizationAttributionInput",
"description": "Attribution job from optimization result."
}
],
"title": "Job Input",
"description": "Source job (simulation/prediction/optimization) for attribution."
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Optional integer seed for reproducible runs. If omitted, the server generates a random seed."
},
"auto_activate": {
"type": "boolean",
"title": "Auto Activate",
"description": "If true, automatically creates and activates an attribution set from this job once it completes.",
"default": false
},
"validate_limits": {
"type": "boolean",
"title": "Validate Limits",
"description": "Validate values against per-variable min/max limits.",
"default": false
}
},
"type": "object",
"required": [
"model_id",
"job_input"
],
"title": "AttributionFromJobRequest",
"description": "Schema for an attribution job using another job as input.\n\nSame as `AttributionRequest`, but `job_input` is required. The dataset (and\nthe prediction fit model, when applicable) is derived from the source job —\n`dataset_id` is ignored.",
"examples": [
{
"baseline": [
{
"baseline": 1000,
"variable": "base_sales"
}
],
"dataset_id": "active",
"end_date": "2024-12-31T00:00:00",
"fit_attribution": false,
"job_input": {
"id": 1,
"job_type": "simulation",
"quantile": 50,
"scenario": "Scenario"
},
"model_id": 1,
"name": "USA Market Attribution Q4",
"note": "Attribution analysis for USA market Q4 2024",
"predicted_targets_as_data": true,
"priority": 30,
"quantiles": [
1,
25,
50,
75,
99
],
"referece_point_fallback": "Min",
"samples": 20,
"start_date": "2024-01-01T00:00:00"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Model": {
"description": "Reference to the trained model used for attribution",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"Fit": {
"type": "boolean",
"title": "Fit",
"description": "Whether this is a fit attribution (FitModelId is set)",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Model",
"Date",
"Fit"
],
"title": "Attribution",
"description": "Response schema for attribution analysis jobs.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00Z",
"Fit": false,
"IId": 1,
"JobId": 123,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "Marketing Model",
"Region": "all"
},
"Name": "Q4 Attribution Analysis",
"Note": "Attribution analysis for Q4 marketing data",
"Status": "completed"
}
]
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Submit Multiple Attributions (/api/attributions/submit_multiple_attributions_projects__team_id___project_id__attributions_multiple_post)
Submit multiple attribution jobs.
Creates multiple attribution jobs to analyze variable impacts within
a project, using specified data and settings.
## POST /api/projects/{team_id}/{project_id}/attributions_multiple
Submit Multiple Attributions
Submit multiple attribution jobs.
Creates multiple attribution jobs to analyze variable impacts within
a project, using specified data and settings.
```json
{
"tags": [
"Attributions"
],
"summary": "Submit Multiple Attributions",
"description": "Submit multiple attribution jobs.\n\nCreates multiple attribution jobs to analyze variable impacts within\na project, using specified data and settings.",
"operationId": "submit_multiple_attributions_projects__team_id___project_id__attributions_multiple_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"names": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Names",
"description": "Name list for the model, the list needs to be the same length with modelling_combinations."
},
"notes": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Notes",
"description": "Description for the model/dataset"
},
"prefixes": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Prefixes",
"description": "Prefix for the name."
},
"samples": {
"type": "integer",
"title": "The samples",
"description": "Hom many subsamples to draw from the posterior distribution. The higher number of samples the better the uncertainty estimation becomes but it also takes longer to run.",
"default": 20
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
},
"dataset_ids": {
"anyOf": [
{
"items": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Dataset Ids",
"description": "List of dataset id to be used for attribution calculation for each model_id, set to None to use active dataset"
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Start Date",
"description": "The first date in the date range used to select data from the dataset"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "End Date",
"description": "The last date in the date range used to select data from the dataset."
},
"quantiles": {
"anyOf": [
{
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Quantiles",
"default": [
1,
25,
50,
75,
99
]
},
"predicted_targets_as_data": {
"type": "boolean",
"title": "Predicted Targets As Data",
"default": true
},
"model_ids": {
"items": {
"type": "integer"
},
"type": "array",
"minItems": 1,
"title": "Model Ids",
"description": "The ids of the model that should be used to do the attribution with. If no one is selected, the `active` models will be used."
},
"fit_attribution": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Fit Attribution",
"description": "Set attribution as fit attribution of the model.",
"default": false
},
"referece_point_fallback": {
"anyOf": [
{
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback",
"description": "Attribution's reference point fallback."
},
{
"type": "null"
}
],
"description": "Reference point fallback.",
"default": "Min"
},
"baseline": {
"anyOf": [
{
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable",
"description": "Variable slug."
},
"baseline": {
"type": "number",
"title": "Baseline",
"description": "Set baseline."
}
},
"type": "object",
"required": [
"variable",
"baseline"
],
"title": "ReferencePointBaseline",
"description": "Attribution job baseline."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Baseline"
},
"updated_values": {
"anyOf": [
{
"additionalProperties": {
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable"
},
"update": {
"anyOf": [
{
"items": {
"prefixItems": [
{
"type": "string",
"format": "date-time",
"title": "Date"
},
{
"type": "number",
"title": "Value"
}
],
"type": "array",
"maxItems": 2,
"minItems": 2
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Update"
}
},
"type": "object",
"required": [
"variable",
"update"
],
"title": "UpdatedVariable",
"description": "Schema for schenario updated variabls values."
},
"type": "array"
},
"propertyNames": {
"const": "scenario"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Updated Values",
"description": "The updated values variable."
},
"job_inputs": {
"anyOf": [
{
"items": {
"anyOf": [
{
"properties": {
"id": {
"type": "integer",
"title": "Id"
},
"quantile": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "Quantile"
},
"scenario": {
"type": "string",
"enum": [
"BaseScenario",
"Scenario"
],
"title": "Scenario"
},
"job_type": {
"type": "string",
"const": "simulation",
"title": "Job Type",
"default": "simulation"
}
},
"type": "object",
"required": [
"id",
"quantile",
"scenario"
],
"title": "SimulationAttributionInput",
"description": "Attribution job from simulation result."
},
{
"properties": {
"id": {
"type": "integer",
"title": "Id"
},
"quantile": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "Quantile"
},
"scenario": {
"type": "string",
"title": "Scenario"
},
"job_type": {
"type": "string",
"const": "prediction",
"title": "Job Type",
"default": "prediction"
}
},
"type": "object",
"required": [
"id",
"quantile",
"scenario"
],
"title": "PredictionAttributionInput",
"description": "Attribution job from prediction result."
},
{
"properties": {
"id": {
"type": "integer",
"title": "Id"
},
"job_type": {
"type": "string",
"const": "optimization",
"title": "Job Type",
"default": "optimization"
}
},
"type": "object",
"required": [
"id"
],
"title": "OptimizationAttributionInput",
"description": "Attribution job from optimization result."
}
],
"description": "job_type"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Job Inputs",
"description": "Run attribution from other job result."
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Optional integer seed for reproducible runs. If omitted, the server generates a random seed shared across the batch."
},
"validate_limits": {
"type": "boolean",
"title": "Validate Limits",
"description": "Validate values against per-variable min/max limits.",
"default": false
}
},
"type": "object",
"required": [
"model_ids"
],
"title": "AttributionMultipleRequest",
"description": "Schemas of attribution multiple request endpoint.",
"examples": [
{
"baseline": [
{
"baseline": 1000,
"variable": "base_sales"
}
],
"dataset_ids": [
"active",
"active",
"active"
],
"end_date": "2024-12-31T00:00:00",
"fit_attribution": false,
"model_ids": [
1,
2,
3
],
"names": [
"USA Attribution",
"GBR Attribution",
"DE Attribution"
],
"notes": [
"USA market analysis",
"GBR market analysis",
"DE market analysis"
],
"predicted_targets_as_data": true,
"priority": 30,
"quantiles": [
1,
25,
50,
75,
99
],
"referece_point_fallback": "Min",
"samples": 20,
"start_date": "2024-01-01T00:00:00"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Model": {
"description": "Reference to the trained model used for attribution",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"Fit": {
"type": "boolean",
"title": "Fit",
"description": "Whether this is a fit attribution (FitModelId is set)",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Model",
"Date",
"Fit"
],
"title": "Attribution",
"description": "Response schema for attribution analysis jobs.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00Z",
"Fit": false,
"IId": 1,
"JobId": 123,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "Marketing Model",
"Region": "all"
},
"Name": "Q4 Attribution Analysis",
"Note": "Attribution analysis for Q4 marketing data",
"Status": "completed"
}
]
},
"title": "Response Submit Multiple Attributions Projects Team Id Project Id Attributions Multiple Post"
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution (/api/attributions/get_attribution_projects__team_id___project_id__attributions__attributionjob_id__get)
Get an attribution.
This endpoint retrieves detailed information about a specific attribution.
## GET /api/projects/{team_id}/{project_id}/attributions/{attributionjob_id}
Get Attribution
Get an attribution.
This endpoint retrieves detailed information about a specific attribution.
```json
{
"tags": [
"Attributions"
],
"summary": "Get Attribution",
"description": "Get an attribution.\n\nThis endpoint retrieves detailed information about a specific attribution.",
"operationId": "get_attribution_projects__team_id___project_id__attributions__attributionjob_id__get",
"parameters": [
{
"name": "attributionjob_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide attribution job IId.",
"title": "Attributionjob Id"
},
"description": "Provide attribution job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"Task": {
"anyOf": [
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"Topic": {
"type": "string",
"enum": [
"ATTRIBUTIONSET",
"ATTRIBUTIONJOB",
"SIMULATIONJOB",
"PREDICTIONJOB",
"TRAINJOB",
"DATASET",
"DATAUPLOAD",
"GRAPHCONSTRUCT",
"GENERAL",
"OPTIMIZATIONJOB",
"RESPOSNSECURVEJOB",
"PRIORPOSTERIORJOB",
"EXCELJOB",
"GRAPHBASIC",
"FEATUREIMPORTANCE",
"GRAPHSYNERGY"
],
"title": "TaskTopics",
"description": "Task topics."
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"Id",
"Config",
"Topic",
"Status"
],
"title": "Task",
"description": "Reference task."
},
{
"type": "null"
}
]
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Model": {
"description": "Reference to the trained model used for attribution",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"AttributionSets": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Selected": {
"type": "boolean",
"title": "Selected"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"IId",
"Selected",
"CreatedDate",
"Status"
],
"title": "AttributionSetRef",
"description": "reference schema for Attribution set."
},
"type": "array",
"title": "Attributionsets",
"description": "Attribution sets that include this job"
},
"StartDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Startdate",
"description": "Attribution analysis start date"
},
"EndDate": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Enddate",
"description": "Attribution analysis end date"
},
"FitModel": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
},
{
"type": "null"
}
],
"description": "Model used for fit-period attribution"
},
"ReferencePointFallback": {
"description": "How to handle missing reference points: 'zero' or 'mean'",
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback"
},
"PredictedTargetsAsData": {
"type": "boolean",
"title": "Predictedtargetsasdata",
"description": "Whether predicted target values are used as input data"
},
"Seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Seed used for reproducible runs"
},
"UpdateVariable": {
"items": {
"properties": {
"Variable": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"Slug": {
"type": "string",
"title": "Slug"
},
"Type": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes",
"description": "Varaible Tyeps."
},
"Group": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups",
"description": "Vraible groups."
}
},
"type": "object",
"required": [
"IId",
"Name",
"Slug",
"Type",
"Group"
],
"title": "VariableRef",
"description": "Variable reference."
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Value": {
"type": "number",
"title": "Value"
}
},
"type": "object",
"required": [
"Variable",
"Date",
"Value"
],
"title": "UpdateVariable",
"description": "Updated variables."
},
"type": "array",
"title": "Updatevariable",
"description": "Variable modifications applied during attribution"
},
"SimulationAssociation": {
"anyOf": [
{
"properties": {
"SimulationJob": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"IsFromOptimization": {
"type": "boolean",
"title": "Isfromoptimization",
"description": "Whether this simulation was submitted by an optimization job.",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"IsFromOptimization"
],
"title": "SimulationJobsRef",
"description": "Reference schema for simulation Job."
},
"Quantile": {
"type": "number",
"title": "Quantile"
},
"Scenario": {
"type": "string",
"title": "Scenario"
}
},
"type": "object",
"required": [
"SimulationJob",
"Quantile",
"Scenario"
],
"title": "AttributionSimulationAssociation",
"description": "Reference schema for attribution simulation association."
},
{
"type": "null"
}
],
"description": "Linked simulation job (if created from simulation)"
},
"PredictionAssociation": {
"anyOf": [
{
"properties": {
"PredictionJob": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status"
],
"title": "PredictionJobsRef",
"description": "Reference schema for prediction job."
},
"Quantile": {
"type": "number",
"title": "Quantile"
},
"Scenario": {
"type": "string",
"title": "Scenario"
}
},
"type": "object",
"required": [
"PredictionJob",
"Quantile",
"Scenario"
],
"title": "AttributionPredictionAssociation",
"description": "Reference schema for attribution prediction association."
},
{
"type": "null"
}
],
"description": "Linked prediction job (if created from prediction)"
},
"OptimizationAssociation": {
"anyOf": [
{
"properties": {
"OptimizationJob": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"type": "integer",
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
}
},
"type": "object",
"required": [
"IId",
"JobId",
"Status"
],
"title": "OptimizationJobsRef",
"description": "Reference schema for optimization job."
}
},
"type": "object",
"required": [
"OptimizationJob"
],
"title": "AttributionOptimizationAssociation",
"description": "Reference schema for attribution optimization association."
},
{
"type": "null"
}
],
"description": "Linked optimization job (if created from optimization)"
},
"Fit": {
"type": "boolean",
"title": "Fit",
"description": "Whether this is a fit attribution (FitModelId is set)",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Model",
"Date",
"AttributionSets",
"ReferencePointFallback",
"PredictedTargetsAsData",
"UpdateVariable",
"Fit"
],
"title": "DetailedAttribution",
"description": "Detailed response schema for attribution jobs with configuration.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00Z",
"IId": 1,
"JobId": 123,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "Marketing Model",
"Region": "all"
},
"Name": "Q4 Attribution Analysis",
"Note": "Attribution analysis for Q4",
"PredictedTargetsAsData": true,
"ReferencePointFallback": "Zero",
"Status": "completed",
"UIFilterAttributionSets": [],
"UpdateVariable": []
}
]
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Attribution (/api/attributions/update_attribution_projects__team_id___project_id__attributions__attributionjob_id__patch)
Update attribution attributes.
Modifies attributes like name or note for a specific attribution job
within a project.
## PATCH /api/projects/{team_id}/{project_id}/attributions/{attributionjob_id}
Update Attribution
Update attribution attributes.
Modifies attributes like name or note for a specific attribution job
within a project.
```json
{
"tags": [
"Attributions"
],
"summary": "Update Attribution",
"description": "Update attribution attributes.\n\nModifies attributes like name or note for a specific attribution job\nwithin a project.",
"operationId": "update_attribution_projects__team_id___project_id__attributions__attributionjob_id__patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "attributionjob_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide attribution job IId.",
"title": "Attributionjob Id"
},
"description": "Provide attribution job IId."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Description for the model/dataset"
}
},
"type": "object",
"title": "PatchAttribution",
"description": "Schema for updating decomposition job.",
"examples": [
{
"Name": "Updated Attribution Name",
"Note": "Updated attribution description"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Model": {
"description": "Reference to the trained model used for attribution",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"Fit": {
"type": "boolean",
"title": "Fit",
"description": "Whether this is a fit attribution (FitModelId is set)",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Model",
"Date",
"Fit"
],
"title": "Attribution",
"description": "Response schema for attribution analysis jobs.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00Z",
"Fit": false,
"IId": 1,
"JobId": 123,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "Marketing Model",
"Region": "all"
},
"Name": "Q4 Attribution Analysis",
"Note": "Attribution analysis for Q4 marketing data",
"Status": "completed"
}
]
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Attribution (/api/attributions/delete_attribution_projects__team_id___project_id__attributions__attributionjob_id__delete)
Delete an attribution.
Removes a specific attribution job and its data from a project.
## DELETE /api/projects/{team_id}/{project_id}/attributions/{attributionjob_id}
Delete Attribution
Delete an attribution.
Removes a specific attribution job and its data from a project.
```json
{
"tags": [
"Attributions"
],
"summary": "Delete Attribution",
"description": "Delete an attribution.\n\nRemoves a specific attribution job and its data from a project.",
"operationId": "delete_attribution_projects__team_id___project_id__attributions__attributionjob_id__delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "attributionjob_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide attribution job IId.",
"title": "Attributionjob Id"
},
"description": "Provide attribution job IId."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution Dates Min Max (/api/attributions/get_attribution_dates_min_max_projects__team_id___project_id__attributions__attributionjob_id__dates_min_max_get)
Get min and max dates from attribution results.
## GET /api/projects/{team_id}/{project_id}/attributions/{attributionjob_id}/dates_min_max
Get Attribution Dates Min Max
Get min and max dates from attribution results.
```json
{
"tags": [
"Attributions"
],
"summary": "Get Attribution Dates Min Max",
"description": "Get min and max dates from attribution results.",
"operationId": "get_attribution_dates_min_max_projects__team_id___project_id__attributions__attributionjob_id__dates_min_max_get",
"parameters": [
{
"name": "attributionjob_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide attribution job IId.",
"title": "Attributionjob Id"
},
"description": "Provide attribution job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"min": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Min"
},
"max": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Max"
}
},
"type": "object",
"required": [
"min",
"max"
],
"title": "DateRange",
"description": "Min and max dates for a resource collection."
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution Baseline (/api/attributions/get_attribution_baseline_projects__team_id___project_id__attributions__attributionjob_id__baseline_get)
Get baseline values for an attribution.
Returns the per-variable baseline values used in the attribution decomposition.
## GET /api/projects/{team_id}/{project_id}/attributions/{attributionjob_id}/baseline
Get Attribution Baseline
Get baseline values for an attribution.
Returns the per-variable baseline values used in the attribution decomposition.
```json
{
"tags": [
"Attributions"
],
"summary": "Get Attribution Baseline",
"description": "Get baseline values for an attribution.\n\nReturns the per-variable baseline values used in the attribution decomposition.",
"operationId": "get_attribution_baseline_projects__team_id___project_id__attributions__attributionjob_id__baseline_get",
"parameters": [
{
"name": "attributionjob_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide attribution job IId.",
"title": "Attributionjob Id"
},
"description": "Provide attribution job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Variable": {
"properties": {
"Slug": {
"type": "string",
"title": "Slug"
}
},
"type": "object",
"required": [
"Slug"
],
"title": "_Variable"
},
"Baseline": {
"type": "number",
"title": "Baseline"
}
},
"type": "object",
"required": [
"Variable",
"Baseline"
],
"title": "AttrBaseline",
"description": "Schema for attribution baseline values."
},
"title": "Response Get Attribution Baseline Projects Team Id Project Id Attributions Attributionjob Id Baseline Get"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Attribution (/api/attributions/download_attribution_projects__team_id___project_id__attributions__attributionjob_id__data_get)
Get attribution job result data.
Retrieves results of a specific attribution job in CSV or Parquet
format, with optional filters.
## GET /api/projects/{team_id}/{project_id}/attributions/{attributionjob_id}/data
Download Attribution
Get attribution job result data.
Retrieves results of a specific attribution job in CSV or Parquet
format, with optional filters.
```json
{
"tags": [
"Attributions"
],
"summary": "Download Attribution",
"description": "Get attribution job result data.\n\nRetrieves results of a specific attribution job in CSV or Parquet\nformat, with optional filters.",
"operationId": "download_attribution_projects__team_id___project_id__attributions__attributionjob_id__data_get",
"parameters": [
{
"name": "attributionjob_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide attribution job IId.",
"title": "Attributionjob Id"
},
"description": "Provide attribution job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "result_filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n Filter attribution result data rows.\n\n Examples:\n - By country: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - Multiple: result_filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"media\"]]}'\n - By response: result_filters='{\"Response\": [[\"=\", \"sales\"]]}'\n ",
"title": "Result Filters"
},
"description": "\n Filter attribution result data rows.\n\n Examples:\n - By country: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - Multiple: result_filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"media\"]]}'\n - By response: result_filters='{\"Response\": [[\"=\", \"sales\"]]}'\n "
},
{
"name": "output_format",
"in": "query",
"required": false,
"schema": {
"enum": [
"csv",
"parquet"
],
"type": "string",
"default": "csv",
"title": "Output Format"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Attribution Query (/api/attributions/download_attribution_query_projects__team_id___project_id__attributions__attributionjob_id__data_query_post)
Get attribution job result data — POST variant for large filter payloads.
## POST /api/projects/{team_id}/{project_id}/attributions/{attributionjob_id}/data_query
Download Attribution Query
Get attribution job result data — POST variant for large filter payloads.
```json
{
"tags": [
"Attributions"
],
"summary": "Download Attribution Query",
"description": "Get attribution job result data — POST variant for large filter payloads.",
"operationId": "download_attribution_query_projects__team_id___project_id__attributions__attributionjob_id__data_query_post",
"parameters": [
{
"name": "attributionjob_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide attribution job IId.",
"title": "Attributionjob Id"
},
"description": "Provide attribution job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"result_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Result Filters"
},
"output_format": {
"type": "string",
"enum": [
"csv",
"parquet"
],
"title": "Output Format",
"default": "csv"
}
},
"type": "object",
"title": "ResultFiltersBody",
"description": "Request body for _query POST endpoints that filter result data rows."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution Group Metrics (/api/attributions/get_attribution_group_metrics_projects__team_id___project_id__attributions__attributionjob_id__group_metrics_get)
Get effect/share rows from AttributionGroupMetrics for a completed attribution.
Returns rows for every effect Type (Total, Direct, Indirect) by default;
pass a Type filter to narrow to one.
## GET /api/projects/{team_id}/{project_id}/attributions/{attributionjob_id}/group_metrics
Get Attribution Group Metrics
Get effect/share rows from AttributionGroupMetrics for a completed attribution.
Returns rows for every effect Type (Total, Direct, Indirect) by default;
pass a Type filter to narrow to one.
```json
{
"tags": [
"Attributions"
],
"summary": "Get Attribution Group Metrics",
"description": "Get effect/share rows from AttributionGroupMetrics for a completed attribution.\n\nReturns rows for every effect Type (Total, Direct, Indirect) by default;\npass a Type filter to narrow to one.",
"operationId": "get_attribution_group_metrics_projects__team_id___project_id__attributions__attributionjob_id__group_metrics_get",
"parameters": [
{
"name": "attributionjob_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide attribution job IId.",
"title": "Attributionjob Id"
},
"description": "Provide attribution job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By group: filters='{\"VarGroup\": [[\"=\", \"Media\"]]}'\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By group: filters='{\"VarGroup\": [[\"=\", \"Media\"]]}'\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n "
},
{
"name": "include_util_attr",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "If true, include RespUtilAttr (parsed util attributes) per row.",
"default": true,
"title": "Include Util Attr"
},
"description": "If true, include RespUtilAttr (parsed util attributes) per row."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"AttributionId": {
"type": "integer",
"title": "Attributionid"
},
"CombinationId": {
"type": "integer",
"title": "Combinationid"
},
"VarGroup": {
"type": "string",
"title": "Vargroup"
},
"RespIId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Respiid"
},
"Type": {
"type": "string",
"enum": [
"Direct",
"Indirect",
"Total"
],
"title": "AttrEffectTypes",
"description": "Attribution Effect Types."
},
"SumEffect": {
"type": "number",
"title": "Sumeffect"
},
"ShareOfEffect": {
"type": "number",
"title": "Shareofeffect"
},
"RespUtilAttr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"Id",
"AttributionId",
"CombinationId",
"VarGroup",
"RespIId",
"Type",
"SumEffect",
"ShareOfEffect"
],
"title": "AttributionGroupMetric",
"description": "Response schema for AttributionGroupMetrics — effect/share per group."
},
"title": "Response Get Attribution Group Metrics Projects Team Id Project Id Attributions Attributionjob Id Group Metrics Get"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution Variable Metrics (/api/attributions/get_attribution_variable_metrics_projects__team_id___project_id__attributions__attributionjob_id__variable_metrics_get)
Get effect/share rows from AttributionVariableMetrics for a completed attribution.
Returns rows for every effect Type (Total, Direct, Indirect) by default;
pass a Type filter to narrow to one.
## GET /api/projects/{team_id}/{project_id}/attributions/{attributionjob_id}/variable_metrics
Get Attribution Variable Metrics
Get effect/share rows from AttributionVariableMetrics for a completed attribution.
Returns rows for every effect Type (Total, Direct, Indirect) by default;
pass a Type filter to narrow to one.
```json
{
"tags": [
"Attributions"
],
"summary": "Get Attribution Variable Metrics",
"description": "Get effect/share rows from AttributionVariableMetrics for a completed attribution.\n\nReturns rows for every effect Type (Total, Direct, Indirect) by default;\npass a Type filter to narrow to one.",
"operationId": "get_attribution_variable_metrics_projects__team_id___project_id__attributions__attributionjob_id__variable_metrics_get",
"parameters": [
{
"name": "attributionjob_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide attribution job IId.",
"title": "Attributionjob Id"
},
"description": "Provide attribution job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "var_group",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by variable group (e.g. Media, CustomerExperience).",
"title": "Var Group"
},
"description": "Filter by variable group (e.g. Media, CustomerExperience)."
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By group: filters='{\"VarGroup\": [[\"=\", \"Media\"]]}'\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By group: filters='{\"VarGroup\": [[\"=\", \"Media\"]]}'\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n "
},
{
"name": "include_util_attr",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "If true, include VarUtilAttr/RespUtilAttr (parsed util attributes) per row.",
"default": true,
"title": "Include Util Attr"
},
"description": "If true, include VarUtilAttr/RespUtilAttr (parsed util attributes) per row."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"AttributionId": {
"type": "integer",
"title": "Attributionid"
},
"CombinationId": {
"type": "integer",
"title": "Combinationid"
},
"VarIId": {
"type": "integer",
"title": "Variid"
},
"VarSlug": {
"type": "string",
"title": "Varslug"
},
"VarGroup": {
"type": "string",
"title": "Vargroup"
},
"RespIId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Respiid"
},
"Type": {
"type": "string",
"enum": [
"Direct",
"Indirect",
"Total"
],
"title": "AttrEffectTypes",
"description": "Attribution Effect Types."
},
"SumEffect": {
"type": "number",
"title": "Sumeffect"
},
"ShareOfEffect": {
"type": "number",
"title": "Shareofeffect"
},
"VarUtilAttr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
]
},
"RespUtilAttr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"Id",
"AttributionId",
"CombinationId",
"VarIId",
"VarSlug",
"VarGroup",
"RespIId",
"Type",
"SumEffect",
"ShareOfEffect"
],
"title": "AttributionVariableMetric",
"description": "Response schema for AttributionVariableMetrics — effect/share per variable."
},
"title": "Response Get Attribution Variable Metrics Projects Team Id Project Id Attributions Attributionjob Id Variable Metrics Get"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution Totals (/api/attributions/get_attribution_totals_projects__team_id___project_id__attributions__attributionjob_id__totals_get)
Get TotalEffect rows from AttributionTotals for a completed attribution.
Returns rows for every effect Type (Total, Direct, Indirect) by default;
pass a Type filter to narrow to one.
## GET /api/projects/{team_id}/{project_id}/attributions/{attributionjob_id}/totals
Get Attribution Totals
Get TotalEffect rows from AttributionTotals for a completed attribution.
Returns rows for every effect Type (Total, Direct, Indirect) by default;
pass a Type filter to narrow to one.
```json
{
"tags": [
"Attributions"
],
"summary": "Get Attribution Totals",
"description": "Get TotalEffect rows from AttributionTotals for a completed attribution.\n\nReturns rows for every effect Type (Total, Direct, Indirect) by default;\npass a Type filter to narrow to one.",
"operationId": "get_attribution_totals_projects__team_id___project_id__attributions__attributionjob_id__totals_get",
"parameters": [
{
"name": "attributionjob_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide attribution job IId.",
"title": "Attributionjob Id"
},
"description": "Provide attribution job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - Grand totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - Grand totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n "
},
{
"name": "include_util_attr",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "If true, include RespUtilAttr (parsed util attributes) per row.",
"default": true,
"title": "Include Util Attr"
},
"description": "If true, include RespUtilAttr (parsed util attributes) per row."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"AttributionId": {
"type": "integer",
"title": "Attributionid"
},
"CombinationId": {
"type": "integer",
"title": "Combinationid"
},
"RespIId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Respiid"
},
"Type": {
"type": "string",
"enum": [
"Direct",
"Indirect",
"Total"
],
"title": "AttrEffectTypes",
"description": "Attribution Effect Types."
},
"TotalEffect": {
"type": "number",
"title": "Totaleffect"
},
"RespUtilAttr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"Id",
"AttributionId",
"CombinationId",
"RespIId",
"Type",
"TotalEffect"
],
"title": "AttributionTotal",
"description": "Response schema for AttributionTotals — shared TotalEffect denominator."
},
"title": "Response Get Attribution Totals Projects Team Id Project Id Attributions Attributionjob Id Totals Get"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution Group Roi (/api/attributions/get_attribution_group_roi_projects__team_id___project_id__attributions__attributionjob_id__group_roi_get)
Get investment/ROI rows from AttributionGroupROI for a completed attribution.
Returns rows for every effect Type (Total, Direct, Indirect) by default;
pass a Type filter to narrow to one.
## GET /api/projects/{team_id}/{project_id}/attributions/{attributionjob_id}/group_roi
Get Attribution Group Roi
Get investment/ROI rows from AttributionGroupROI for a completed attribution.
Returns rows for every effect Type (Total, Direct, Indirect) by default;
pass a Type filter to narrow to one.
```json
{
"tags": [
"Attributions"
],
"summary": "Get Attribution Group Roi",
"description": "Get investment/ROI rows from AttributionGroupROI for a completed attribution.\n\nReturns rows for every effect Type (Total, Direct, Indirect) by default;\npass a Type filter to narrow to one.",
"operationId": "get_attribution_group_roi_projects__team_id___project_id__attributions__attributionjob_id__group_roi_get",
"parameters": [
{
"name": "attributionjob_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide attribution job IId.",
"title": "Attributionjob Id"
},
"description": "Provide attribution job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By group: filters='{\"VarGroup\": [[\"=\", \"Media\"]]}'\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - High ROI: filters='{\"EffectROI\": [[\">=\", \"2\"]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By group: filters='{\"VarGroup\": [[\"=\", \"Media\"]]}'\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - High ROI: filters='{\"EffectROI\": [[\">=\", \"2\"]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n "
},
{
"name": "include_util_attr",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "If true, include RespUtilAttr (parsed util attributes) per row.",
"default": true,
"title": "Include Util Attr"
},
"description": "If true, include RespUtilAttr (parsed util attributes) per row."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"AttributionId": {
"type": "integer",
"title": "Attributionid"
},
"CombinationId": {
"type": "integer",
"title": "Combinationid"
},
"VarGroup": {
"type": "string",
"title": "Vargroup"
},
"RespIId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Respiid"
},
"Type": {
"type": "string",
"enum": [
"Direct",
"Indirect",
"Total"
],
"title": "AttrEffectTypes",
"description": "Attribution Effect Types."
},
"Investment": {
"type": "number",
"title": "Investment"
},
"CPX": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Cpx"
},
"EffectROI": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Effectroi"
},
"RevenueROI": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Revenueroi"
},
"ProfitROI": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Profitroi"
},
"RespUtilAttr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"Id",
"AttributionId",
"CombinationId",
"VarGroup",
"RespIId",
"Type",
"Investment",
"CPX",
"EffectROI",
"RevenueROI",
"ProfitROI"
],
"title": "AttributionGroupROIMetric",
"description": "Response schema for AttributionGroupROI — investment/ROI for Media/CX groups."
},
"title": "Response Get Attribution Group Roi Projects Team Id Project Id Attributions Attributionjob Id Group Roi Get"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution Variable Roi (/api/attributions/get_attribution_variable_roi_projects__team_id___project_id__attributions__attributionjob_id__variable_roi_get)
Get investment/ROI rows from AttributionVariableROI for a completed attribution.
Returns rows for every effect Type (Total, Direct, Indirect) by default;
pass a Type filter to narrow to one.
## GET /api/projects/{team_id}/{project_id}/attributions/{attributionjob_id}/variable_roi
Get Attribution Variable Roi
Get investment/ROI rows from AttributionVariableROI for a completed attribution.
Returns rows for every effect Type (Total, Direct, Indirect) by default;
pass a Type filter to narrow to one.
```json
{
"tags": [
"Attributions"
],
"summary": "Get Attribution Variable Roi",
"description": "Get investment/ROI rows from AttributionVariableROI for a completed attribution.\n\nReturns rows for every effect Type (Total, Direct, Indirect) by default;\npass a Type filter to narrow to one.",
"operationId": "get_attribution_variable_roi_projects__team_id___project_id__attributions__attributionjob_id__variable_roi_get",
"parameters": [
{
"name": "attributionjob_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide attribution job IId.",
"title": "Attributionjob Id"
},
"description": "Provide attribution job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - High ROI: filters='{\"EffectROI\": [[\">=\", \"2\"]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - High ROI: filters='{\"EffectROI\": [[\">=\", \"2\"]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n "
},
{
"name": "include_util_attr",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "If true, include VarUtilAttr/RespUtilAttr (parsed util attributes) per row.",
"default": true,
"title": "Include Util Attr"
},
"description": "If true, include VarUtilAttr/RespUtilAttr (parsed util attributes) per row."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"AttributionId": {
"type": "integer",
"title": "Attributionid"
},
"CombinationId": {
"type": "integer",
"title": "Combinationid"
},
"VarIId": {
"type": "integer",
"title": "Variid"
},
"RespIId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Respiid"
},
"Type": {
"type": "string",
"enum": [
"Direct",
"Indirect",
"Total"
],
"title": "AttrEffectTypes",
"description": "Attribution Effect Types."
},
"Investment": {
"type": "number",
"title": "Investment"
},
"CPX": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Cpx"
},
"EffectROI": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Effectroi"
},
"RevenueROI": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Revenueroi"
},
"ProfitROI": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Profitroi"
},
"VarUtilAttr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
]
},
"RespUtilAttr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"Id",
"AttributionId",
"CombinationId",
"VarIId",
"RespIId",
"Type",
"Investment",
"CPX",
"EffectROI",
"RevenueROI",
"ProfitROI"
],
"title": "AttributionVariableROIMetric",
"description": "Response schema for AttributionVariableROI — investment/ROI for Media/CX variables."
},
"title": "Response Get Attribution Variable Roi Projects Team Id Project Id Attributions Attributionjob Id Variable Roi Get"
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Attribution Sets (/api/attribution-sets/list_attribution_sets_projects__team_id___project_id__attributionset_get)
List all attribution sets in the project with optional filtering.
Returns a paginated list of attribution sets, useful for finding
available dashboard views or auditing attribution history.
Query Parameters:
- filters: JSON filter expressions to narrow results
Example: '{"Status": [["=", "COMPLETE"]], "Selected": [["=", true]]}'
Response:
Paginated list of attribution sets.
Related:
- GET /attributionset/{attributionset_id}: Get full details
- POST /attributionset: Create a new attribution set
## GET /api/projects/{team_id}/{project_id}/attributionset
List Attribution Sets
List all attribution sets in the project with optional filtering.
Returns a paginated list of attribution sets, useful for finding
available dashboard views or auditing attribution history.
Query Parameters:
- filters: JSON filter expressions to narrow results
Example: '{"Status": [["=", "COMPLETE"]], "Selected": [["=", true]]}'
Response:
Paginated list of attribution sets.
Related:
- GET /attributionset/{attributionset_id}: Get full details
- POST /attributionset: Create a new attribution set
```json
{
"tags": [
"Attribution Sets"
],
"summary": "List Attribution Sets",
"description": "List all attribution sets in the project with optional filtering.\n\nReturns a paginated list of attribution sets, useful for finding\navailable dashboard views or auditing attribution history.\n\nQuery Parameters:\n - filters: JSON filter expressions to narrow results\n Example: '{\"Status\": [[\"=\", \"COMPLETE\"]], \"Selected\": [[\"=\", true]]}'\n\nResponse:\n Paginated list of attribution sets.\n\nRelated:\n - GET /attributionset/{attributionset_id}: Get full details\n - POST /attributionset: Create a new attribution set",
"operationId": "list_attribution_sets_projects__team_id___project_id__attributionset_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Multiple filters create OR logic.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"complete\"]]}'\n - Active sets only: filters='{\"Selected\": [[\"=\", \"true\"]]}'\n - By name: filters='{\"Name\": [[\"contains\", \"Q4\"]]}'\n - Recent sets: filters='{\"CreatedDate\": [[\">=\", \"2024-10-01\"]]}'\n - By dataset: filters='{\"DataSet.Name\": [[\"contains\", \"Marketing\"]]}'\n - Sort by date: filters='{\"CreatedDate\": [[\"orderby\", \"desc\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Multiple filters create OR logic.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"complete\"]]}'\n - Active sets only: filters='{\"Selected\": [[\"=\", \"true\"]]}'\n - By name: filters='{\"Name\": [[\"contains\", \"Q4\"]]}'\n - Recent sets: filters='{\"CreatedDate\": [[\">=\", \"2024-10-01\"]]}'\n - By dataset: filters='{\"DataSet.Name\": [[\"contains\", \"Marketing\"]]}'\n - Sort by date: filters='{\"CreatedDate\": [[\"orderby\", \"desc\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active attribution set for the dashboard"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Set creation timestamp"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the set"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Processing state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"CreationFilters": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Creationfilters",
"description": "Filters for auto-generating attributions (Country/Region)"
},
"Attributions": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
},
"type": "array",
"title": "Attributions",
"description": "List of attribution jobs included in this set"
},
"DataSet": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
{
"type": "null"
}
],
"description": "Reference to the associated dataset"
}
},
"type": "object",
"required": [
"IId",
"Selected",
"CreatedDate",
"Status",
"Attributions"
],
"title": "AttributionSet",
"description": "Response schema for attribution sets (grouped attribution analyses).",
"examples": [
{
"Attributions": [
{
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00Z",
"IId": 1,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "Marketing Model",
"Region": "all"
},
"Name": "Attribution 1",
"Status": "completed"
}
],
"CreatedDate": "2024-01-15T10:30:00Z",
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"IId": 1,
"Name": "Q4 Attribution Set",
"Note": "Combined attribution analysis for Q4",
"Selected": true,
"Status": "complete"
}
]
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[AttributionSet]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Create Attribution Set (/api/attribution-sets/create_attribution_set_projects__team_id___project_id__attributionset_post)
Create an attribution set from attribution jobs for dashboard display.
Attribution sets aggregate results from multiple attribution jobs into a
unified view for the Effect Dashboard. Use this to combine attributions
across time periods, models, or market segments.
Use Cases:
- Combine quarterly attributions into annual view
- Merge attributions from multiple models for cross-market analysis
- Create filtered views focusing on specific variables or date ranges
Workflow:
1. Run attribution jobs (from predictions/simulations/models)
2. Wait for attribution jobs to reach COMPLETED status
3. Create attribution set using this endpoint
4. Poll GET /attributionset/{attributionset_id} until Status is COMPLETE
5. Activate to display in Effect Dashboard
Response:
Returns the created attribution set. Poll status until COMPLETE.
Related:
- GET /attributionset/{attributionset_id}: Poll status
- PATCH /attributionset/{attributionset_id}/activate: Set as active
- GET /attributionset/{attributionset_id}/data: Download merged results
## POST /api/projects/{team_id}/{project_id}/attributionset
Create Attribution Set
Create an attribution set from attribution jobs for dashboard display.
Attribution sets aggregate results from multiple attribution jobs into a
unified view for the Effect Dashboard. Use this to combine attributions
across time periods, models, or market segments.
Use Cases:
- Combine quarterly attributions into annual view
- Merge attributions from multiple models for cross-market analysis
- Create filtered views focusing on specific variables or date ranges
Workflow:
1. Run attribution jobs (from predictions/simulations/models)
2. Wait for attribution jobs to reach COMPLETED status
3. Create attribution set using this endpoint
4. Poll GET /attributionset/{attributionset_id} until Status is COMPLETE
5. Activate to display in Effect Dashboard
Response:
Returns the created attribution set. Poll status until COMPLETE.
Related:
- GET /attributionset/{attributionset_id}: Poll status
- PATCH /attributionset/{attributionset_id}/activate: Set as active
- GET /attributionset/{attributionset_id}/data: Download merged results
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Create Attribution Set",
"description": "Create an attribution set from attribution jobs for dashboard display.\n\nAttribution sets aggregate results from multiple attribution jobs into a\nunified view for the Effect Dashboard. Use this to combine attributions\nacross time periods, models, or market segments.\n\nUse Cases:\n - Combine quarterly attributions into annual view\n - Merge attributions from multiple models for cross-market analysis\n - Create filtered views focusing on specific variables or date ranges\n\nWorkflow:\n 1. Run attribution jobs (from predictions/simulations/models)\n 2. Wait for attribution jobs to reach COMPLETED status\n 3. Create attribution set using this endpoint\n 4. Poll GET /attributionset/{attributionset_id} until Status is COMPLETE\n 5. Activate to display in Effect Dashboard\n\nResponse:\n Returns the created attribution set. Poll status until COMPLETE.\n\nRelated:\n - GET /attributionset/{attributionset_id}: Poll status\n - PATCH /attributionset/{attributionset_id}/activate: Set as active\n - GET /attributionset/{attributionset_id}/data: Download merged results",
"operationId": "create_attribution_set_projects__team_id___project_id__attributionset_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"attributionjob_ids": {
"anyOf": [
{
"items": {
"anyOf": [
{
"type": "integer"
},
{
"properties": {
"attribution_id": {
"type": "integer",
"title": "Attribution Id",
"description": "The id of the attribution job."
},
"order": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Order",
"description": "Priority order for overlapping results (lower = higher priority). Defaults to list position."
}
},
"type": "object",
"required": [
"attribution_id"
],
"title": "AttributionFilters",
"description": "Attribution filters for the attribution set."
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attributionjob Ids",
"description": "List of attribution job IDs (integers) or filter objects to include. Referenced jobs must be in COMPLETED status. Use filter objects to apply variable/date filters when merging."
},
"activate": {
"type": "boolean",
"title": "Activate",
"description": "Set to true to make this the active attribution set for the Effects Dashboard immediately after creation completes.",
"default": false
},
"attributionset_ids": {
"anyOf": [
{
"items": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "AttributionSetType",
"description": "Attribution set type."
},
{
"properties": {
"attributionset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "AttributionSetType",
"description": "Attribution set type."
}
],
"title": "Attributionset Id",
"description": "The id of the attribution set."
},
"order": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Order",
"description": "Priority order for overlapping results (lower = higher priority). Defaults to list position."
}
},
"type": "object",
"required": [
"attributionset_id"
],
"title": "AttributionSetFilters",
"description": "Attribution set filters for the attribution set."
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attributionset Ids",
"description": "List of existing attribution set IDs to merge into this set. Use 'active' to reference the currently active set, or filter objects to apply variable filters when merging."
}
},
"type": "object",
"title": "AttributionSetRequest",
"description": "Schema for attribution set creation.",
"examples": [
{
"activate": true,
"attributionjob_ids": [
1,
2,
{
"attribution_id": 3,
"variable_filters": [
{
"end_date": "2024-06-30T00:00:00",
"start_date": "2024-01-01T00:00:00",
"variable_id": 101
}
]
}
],
"attributionset_ids": [
"active"
],
"creation_filter": [
"country:USA",
"region:all"
],
"name": "Q4 Attribution Set",
"note": "Combined attribution analysis for Q4 campaigns"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active attribution set for the dashboard"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Set creation timestamp"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the set"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Processing state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"CreationFilters": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Creationfilters",
"description": "Filters for auto-generating attributions (Country/Region)"
},
"Attributions": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
},
"type": "array",
"title": "Attributions",
"description": "List of attribution jobs included in this set"
},
"DataSet": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
{
"type": "null"
}
],
"description": "Reference to the associated dataset"
}
},
"type": "object",
"required": [
"IId",
"Selected",
"CreatedDate",
"Status",
"Attributions"
],
"title": "AttributionSet",
"description": "Response schema for attribution sets (grouped attribution analyses).",
"examples": [
{
"Attributions": [
{
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00Z",
"IId": 1,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "Marketing Model",
"Region": "all"
},
"Name": "Attribution 1",
"Status": "completed"
}
],
"CreatedDate": "2024-01-15T10:30:00Z",
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"IId": 1,
"Name": "Q4 Attribution Set",
"Note": "Combined attribution analysis for Q4",
"Selected": true,
"Status": "complete"
}
]
}
}
}
},
"400": {
"description": "Invalid attribution set request: referenced attribution job not found or not in COMPLETED status, invalid variable filters, or circular reference",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Project is in read-only state",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Bulk Delete Attribution Sets (/api/attribution-sets/bulk_delete_attribution_sets_projects__team_id___project_id__attributionset_delete)
Bulk delete attribution sets matching the given filters.
Marks all matching sets for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
The active (Selected) attribution set is excluded.
## DELETE /api/projects/{team_id}/{project_id}/attributionset
Bulk Delete Attribution Sets
Bulk delete attribution sets matching the given filters.
Marks all matching sets for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
The active (Selected) attribution set is excluded.
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Bulk Delete Attribution Sets",
"description": "Bulk delete attribution sets matching the given filters.\n\nMarks all matching sets for deletion and publishes delete messages to\nRabbitMQ concurrently in the background via a single DB round-trip each.\nThe active (Selected) attribution set is excluded.",
"operationId": "bulk_delete_attribution_sets_projects__team_id___project_id__attributionset_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /attributionset.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"complete\"]]}'\n - By name: filters='{\"Name\": [[\"contains\", \"Q4\"]]}'\n - By date: filters='{\"CreatedDate\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /attributionset.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"complete\"]]}'\n - By name: filters='{\"Name\": [[\"contains\", \"Q4\"]]}'\n - By date: filters='{\"CreatedDate\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n "
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Create Attribution Set Align Dates (/api/attribution-sets/create_attribution_set_align_dates_projects__team_id___project_id__attributionset_align_dates_post)
Create an attribution set with automatic date alignment to avoid overlap.
Automatically filters attribution job results to prevent double-counting
when attributions have overlapping date ranges. Earlier attributions take
precedence for overlapping periods.
Use Case:
When you have multiple attributions with overlapping time periods
(e.g., monthly attributions that overlap at boundaries), this endpoint
automatically aligns them to create non-overlapping coverage.
Date Alignment Logic:
- Attributions are sorted by start date
- Each attribution contributes data only for periods after the
previous attribution's end date
- This prevents double-counting effects in overlapping periods
Response:
Returns the created attribution set with aligned date filters applied.
Related:
- POST /attributionset: Create without automatic date alignment
## POST /api/projects/{team_id}/{project_id}/attributionset_align_dates
Create Attribution Set Align Dates
Create an attribution set with automatic date alignment to avoid overlap.
Automatically filters attribution job results to prevent double-counting
when attributions have overlapping date ranges. Earlier attributions take
precedence for overlapping periods.
Use Case:
When you have multiple attributions with overlapping time periods
(e.g., monthly attributions that overlap at boundaries), this endpoint
automatically aligns them to create non-overlapping coverage.
Date Alignment Logic:
- Attributions are sorted by start date
- Each attribution contributes data only for periods after the
previous attribution's end date
- This prevents double-counting effects in overlapping periods
Response:
Returns the created attribution set with aligned date filters applied.
Related:
- POST /attributionset: Create without automatic date alignment
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Create Attribution Set Align Dates",
"description": "Create an attribution set with automatic date alignment to avoid overlap.\n\nAutomatically filters attribution job results to prevent double-counting\nwhen attributions have overlapping date ranges. Earlier attributions take\nprecedence for overlapping periods.\n\nUse Case:\n When you have multiple attributions with overlapping time periods\n (e.g., monthly attributions that overlap at boundaries), this endpoint\n automatically aligns them to create non-overlapping coverage.\n\nDate Alignment Logic:\n - Attributions are sorted by start date\n - Each attribution contributes data only for periods after the\n previous attribution's end date\n - This prevents double-counting effects in overlapping periods\n\nResponse:\n Returns the created attribution set with aligned date filters applied.\n\nRelated:\n - POST /attributionset: Create without automatic date alignment",
"operationId": "create_attribution_set_align_dates_projects__team_id___project_id__attributionset_align_dates_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"attributionjob_ids": {
"items": {
"type": "integer"
},
"type": "array",
"title": "Attributionjob Ids",
"description": "List of attribution job IDs to include. Order matters - earlier jobs take precedence for overlapping date periods. Jobs must be in COMPLETED status."
},
"activate": {
"type": "boolean",
"title": "Activate",
"description": "Set to true to make this the active attribution set for the Effects Dashboard immediately after creation completes.",
"default": false
}
},
"type": "object",
"required": [
"attributionjob_ids"
],
"title": "AttributionSetRequestAlignDates",
"description": "Attributionset request algining dates."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active attribution set for the dashboard"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Set creation timestamp"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the set"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Processing state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"CreationFilters": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Creationfilters",
"description": "Filters for auto-generating attributions (Country/Region)"
},
"Attributions": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
},
"type": "array",
"title": "Attributions",
"description": "List of attribution jobs included in this set"
},
"DataSet": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
{
"type": "null"
}
],
"description": "Reference to the associated dataset"
}
},
"type": "object",
"required": [
"IId",
"Selected",
"CreatedDate",
"Status",
"Attributions"
],
"title": "AttributionSet",
"description": "Response schema for attribution sets (grouped attribution analyses).",
"examples": [
{
"Attributions": [
{
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00Z",
"IId": 1,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "Marketing Model",
"Region": "all"
},
"Name": "Attribution 1",
"Status": "completed"
}
],
"CreatedDate": "2024-01-15T10:30:00Z",
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"IId": 1,
"Name": "Q4 Attribution Set",
"Note": "Combined attribution analysis for Q4",
"Selected": true,
"Status": "complete"
}
]
}
}
}
},
"400": {
"description": "Invalid attribution set request: referenced attribution job not found or not in COMPLETED status, invalid variable filters, or circular reference",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Project is in read-only state",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Attribution Set Active History (/api/attribution-sets/list_attribution_set_active_history_projects__team_id___project_id__attributionset_active_history_get)
List the history of active attribution set changes for this project.
## GET /api/projects/{team_id}/{project_id}/attributionset/active-history
List Attribution Set Active History
List the history of active attribution set changes for this project.
```json
{
"tags": [
"Attribution Sets"
],
"summary": "List Attribution Set Active History",
"description": "List the history of active attribution set changes for this project.",
"operationId": "list_attribution_set_active_history_projects__team_id___project_id__attributionset_active_history_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "JSON filter expressions. Filterable fields: UpdatedAt (>=, <=), UpdatedByUser (=, contains), AttributionSetId (=, in). Example: filters='{\"UpdatedByUser\": [[\"=\", \"alice\"]]}'",
"title": "Filters"
},
"description": "JSON filter expressions. Filterable fields: UpdatedAt (>=, <=), UpdatedByUser (=, contains), AttributionSetId (=, in). Example: filters='{\"UpdatedByUser\": [[\"=\", \"alice\"]]}'"
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"AttributionSetId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Attributionsetid"
},
"UpdatedByUser": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updatedbyuser"
},
"UpdatedAt": {
"type": "string",
"format": "date-time",
"title": "Updatedat"
}
},
"type": "object",
"required": [
"Id",
"AttributionSetId",
"UpdatedByUser",
"UpdatedAt"
],
"title": "AttributionSetActiveHistory",
"description": "Response schema for attribution set active history records."
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[AttributionSetActiveHistory]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution Set (/api/attribution-sets/get_attribution_set_projects__team_id___project_id__attributionset__attributionset_id__get)
Get detailed information about a specific attribution set.
Use this endpoint to check processing status, view included attributions,
and access metadata. Poll until Status is COMPLETE before downloading
results or activating for dashboard.
Path Parameters:
- attributionset_id: The IId of the attribution set (or "active")
Response:
Detailed attribution set object with task progress info.
Related:
- GET /attributionset/{attributionset_id}/data: Download results
- PATCH /attributionset/{attributionset_id}/activate: Set as active
## GET /api/projects/{team_id}/{project_id}/attributionset/{attributionset_id}
Get Attribution Set
Get detailed information about a specific attribution set.
Use this endpoint to check processing status, view included attributions,
and access metadata. Poll until Status is COMPLETE before downloading
results or activating for dashboard.
Path Parameters:
- attributionset_id: The IId of the attribution set (or "active")
Response:
Detailed attribution set object with task progress info.
Related:
- GET /attributionset/{attributionset_id}/data: Download results
- PATCH /attributionset/{attributionset_id}/activate: Set as active
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Get Attribution Set",
"description": "Get detailed information about a specific attribution set.\n\nUse this endpoint to check processing status, view included attributions,\nand access metadata. Poll until Status is COMPLETE before downloading\nresults or activating for dashboard.\n\nPath Parameters:\n - attributionset_id: The IId of the attribution set (or \"active\")\n\nResponse:\n Detailed attribution set object with task progress info.\n\nRelated:\n - GET /attributionset/{attributionset_id}/data: Download results\n - PATCH /attributionset/{attributionset_id}/activate: Set as active",
"operationId": "get_attribution_set_projects__team_id___project_id__attributionset__attributionset_id__get",
"parameters": [
{
"name": "attributionset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Provide attribution set IId or use 'active'",
"title": "Attributionset Id"
},
"description": "Provide attribution set IId or use 'active'"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"Task": {
"anyOf": [
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"Topic": {
"type": "string",
"enum": [
"ATTRIBUTIONSET",
"ATTRIBUTIONJOB",
"SIMULATIONJOB",
"PREDICTIONJOB",
"TRAINJOB",
"DATASET",
"DATAUPLOAD",
"GRAPHCONSTRUCT",
"GENERAL",
"OPTIMIZATIONJOB",
"RESPOSNSECURVEJOB",
"PRIORPOSTERIORJOB",
"EXCELJOB",
"GRAPHBASIC",
"FEATUREIMPORTANCE",
"GRAPHSYNERGY"
],
"title": "TaskTopics",
"description": "Task topics."
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"Id",
"Config",
"Topic",
"Status"
],
"title": "Task",
"description": "Reference task."
},
{
"type": "null"
}
]
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active attribution set for the dashboard"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Set creation timestamp"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the set"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Processing state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"CreationFilters": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Creationfilters",
"description": "Filters for auto-generating attributions (Country/Region)"
},
"Attributions": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
},
"type": "array",
"title": "Attributions",
"description": "List of attribution jobs included in this set"
},
"DataSet": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
{
"type": "null"
}
],
"description": "Reference to the associated dataset"
}
},
"type": "object",
"required": [
"IId",
"Selected",
"CreatedDate",
"Status",
"Attributions"
],
"title": "DetailedAttributionSet",
"description": "Detailed response schema for attribution sets with task progress.",
"examples": [
{
"Attributions": [
{
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00Z",
"IId": 1,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "Marketing Model",
"Region": "all"
},
"Name": "Attribution 1",
"Status": "completed"
}
],
"CreatedDate": "2024-01-15T10:30:00Z",
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"IId": 1,
"Name": "Q4 Attribution Set",
"Note": "Combined attribution analysis for Q4",
"Selected": true,
"Status": "complete"
}
]
}
}
}
},
"404": {
"description": "Attribution set not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Attribution Set (/api/attribution-sets/update_attribution_set_projects__team_id___project_id__attributionset__attributionset_id__patch)
Update metadata attributes of an attribution set.
Allows modification of mutable fields like Name and Note. Cannot modify
the included attributions after creation.
Response:
Updated attribution set object.
## PATCH /api/projects/{team_id}/{project_id}/attributionset/{attributionset_id}
Update Attribution Set
Update metadata attributes of an attribution set.
Allows modification of mutable fields like Name and Note. Cannot modify
the included attributions after creation.
Response:
Updated attribution set object.
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Update Attribution Set",
"description": "Update metadata attributes of an attribution set.\n\nAllows modification of mutable fields like Name and Note. Cannot modify\nthe included attributions after creation.\n\nResponse:\n Updated attribution set object.",
"operationId": "update_attribution_set_projects__team_id___project_id__attributionset__attributionset_id__patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "attributionset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Provide attribution set IId or use 'active'",
"title": "Attributionset Id"
},
"description": "Provide attribution set IId or use 'active'"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Description for the model/dataset"
}
},
"type": "object",
"title": "PatchAttributionSet",
"description": "schema for updatind attribution jobs.",
"examples": [
{
"Name": "Updated Attribution Set Name",
"Note": "Updated attribution set description"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active attribution set for the dashboard"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Set creation timestamp"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the set"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Processing state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"CreationFilters": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Creationfilters",
"description": "Filters for auto-generating attributions (Country/Region)"
},
"Attributions": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
},
"type": "array",
"title": "Attributions",
"description": "List of attribution jobs included in this set"
},
"DataSet": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
{
"type": "null"
}
],
"description": "Reference to the associated dataset"
}
},
"type": "object",
"required": [
"IId",
"Selected",
"CreatedDate",
"Status",
"Attributions"
],
"title": "AttributionSet",
"description": "Response schema for attribution sets (grouped attribution analyses).",
"examples": [
{
"Attributions": [
{
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00Z",
"IId": 1,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "Marketing Model",
"Region": "all"
},
"Name": "Attribution 1",
"Status": "completed"
}
],
"CreatedDate": "2024-01-15T10:30:00Z",
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"IId": 1,
"Name": "Q4 Attribution Set",
"Note": "Combined attribution analysis for Q4",
"Selected": true,
"Status": "complete"
}
]
}
}
}
},
"404": {
"description": "Attribution set not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Attribution Set (/api/attribution-sets/delete_attribution_set_projects__team_id___project_id__attributionset__attributionset_id__delete)
Delete an attribution set.
Removes the attribution set and its aggregated results. The underlying
attribution jobs are NOT deleted - only the aggregated view.
Path Parameters:
- attributionset_id: The IId of the attribution set to delete
Restrictions:
- Cannot delete the currently active (Selected=True) attribution set
Response:
- success: Boolean indicating deletion completed
- message: Confirmation with the deleted set's IId
Notes:
- Deletion is permanent and cannot be undone
- Deactivate the set first if it's currently active
- Source attribution jobs remain available for new sets
## DELETE /api/projects/{team_id}/{project_id}/attributionset/{attributionset_id}
Delete Attribution Set
Delete an attribution set.
Removes the attribution set and its aggregated results. The underlying
attribution jobs are NOT deleted - only the aggregated view.
Path Parameters:
- attributionset_id: The IId of the attribution set to delete
Restrictions:
- Cannot delete the currently active (Selected=True) attribution set
Response:
- success: Boolean indicating deletion completed
- message: Confirmation with the deleted set's IId
Notes:
- Deletion is permanent and cannot be undone
- Deactivate the set first if it's currently active
- Source attribution jobs remain available for new sets
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Delete Attribution Set",
"description": "Delete an attribution set.\n\nRemoves the attribution set and its aggregated results. The underlying\nattribution jobs are NOT deleted - only the aggregated view.\n\nPath Parameters:\n - attributionset_id: The IId of the attribution set to delete\n\nRestrictions:\n - Cannot delete the currently active (Selected=True) attribution set\n\nResponse:\n - success: Boolean indicating deletion completed\n - message: Confirmation with the deleted set's IId\n\nNotes:\n - Deletion is permanent and cannot be undone\n - Deactivate the set first if it's currently active\n - Source attribution jobs remain available for new sets",
"operationId": "delete_attribution_set_projects__team_id___project_id__attributionset__attributionset_id__delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "attributionset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Provide attribution set IId or use 'active'",
"title": "Attributionset Id"
},
"description": "Provide attribution set IId or use 'active'"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"description": "Cannot delete attribution set: set is currently active (Selected=True). Activate a different set first.",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Attribution set not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution Set Dates Min Max (/api/attribution-sets/get_attribution_set_dates_min_max_projects__team_id___project_id__attributionset__attributionset_id__dates_min_max_get)
Get min and max dates from attribution results within this attribution set.
## GET /api/projects/{team_id}/{project_id}/attributionset/{attributionset_id}/dates_min_max
Get Attribution Set Dates Min Max
Get min and max dates from attribution results within this attribution set.
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Get Attribution Set Dates Min Max",
"description": "Get min and max dates from attribution results within this attribution set.",
"operationId": "get_attribution_set_dates_min_max_projects__team_id___project_id__attributionset__attributionset_id__dates_min_max_get",
"parameters": [
{
"name": "attributionset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Provide attribution set IId or use 'active'",
"title": "Attributionset Id"
},
"description": "Provide attribution set IId or use 'active'"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"min": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Min"
},
"max": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Max"
}
},
"type": "object",
"required": [
"min",
"max"
],
"title": "DateRange",
"description": "Min and max dates for a resource collection."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Activate Attribtuion Set (/api/attribution-sets/activate_attribtuion_set_projects__team_id___project_id__attributionset__attributionset_id__activate_patch)
Set an attribution set as the active dashboard view.
The active attribution set is displayed in the Effect Dashboard and
can be referenced using "active" in API requests. Only one attribution
set per project can be active at a time.
Path Parameters:
- attributionset_id: The IId of the attribution set to activate
Prerequisites:
Attribution set Status must be COMPLETE.
Effects:
- Sets Selected=True for this attribution set
- Deactivates any previously active attribution set
- Effect Dashboard immediately reflects the change
- Sends notification to the user
Response:
Updated attribution set with Selected=True.
Related:
- GET /attributionset: Find attribution sets to activate
- DELETE /attributionset/{attributionset_id}: Cannot delete active sets
## PATCH /api/projects/{team_id}/{project_id}/attributionset/{attributionset_id}/activate
Activate Attribtuion Set
Set an attribution set as the active dashboard view.
The active attribution set is displayed in the Effect Dashboard and
can be referenced using "active" in API requests. Only one attribution
set per project can be active at a time.
Path Parameters:
- attributionset_id: The IId of the attribution set to activate
Prerequisites:
Attribution set Status must be COMPLETE.
Effects:
- Sets Selected=True for this attribution set
- Deactivates any previously active attribution set
- Effect Dashboard immediately reflects the change
- Sends notification to the user
Response:
Updated attribution set with Selected=True.
Related:
- GET /attributionset: Find attribution sets to activate
- DELETE /attributionset/{attributionset_id}: Cannot delete active sets
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Activate Attribtuion Set",
"description": "Set an attribution set as the active dashboard view.\n\nThe active attribution set is displayed in the Effect Dashboard and\ncan be referenced using \"active\" in API requests. Only one attribution\nset per project can be active at a time.\n\nPath Parameters:\n - attributionset_id: The IId of the attribution set to activate\n\nPrerequisites:\n Attribution set Status must be COMPLETE.\n\nEffects:\n - Sets Selected=True for this attribution set\n - Deactivates any previously active attribution set\n - Effect Dashboard immediately reflects the change\n - Sends notification to the user\n\nResponse:\n Updated attribution set with Selected=True.\n\nRelated:\n - GET /attributionset: Find attribution sets to activate\n - DELETE /attributionset/{attributionset_id}: Cannot delete active sets",
"operationId": "activate_attribtuion_set_projects__team_id___project_id__attributionset__attributionset_id__activate_patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "attributionset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Provide attribution set IId or use 'active'",
"title": "Attributionset Id"
},
"description": "Provide attribution set IId or use 'active'"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active attribution set for the dashboard"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Set creation timestamp"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the set"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Processing state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"CreationFilters": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Creationfilters",
"description": "Filters for auto-generating attributions (Country/Region)"
},
"Attributions": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
},
"type": "array",
"title": "Attributions",
"description": "List of attribution jobs included in this set"
},
"DataSet": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
{
"type": "null"
}
],
"description": "Reference to the associated dataset"
}
},
"type": "object",
"required": [
"IId",
"Selected",
"CreatedDate",
"Status",
"Attributions"
],
"title": "AttributionSet",
"description": "Response schema for attribution sets (grouped attribution analyses).",
"examples": [
{
"Attributions": [
{
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00Z",
"IId": 1,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "Marketing Model",
"Region": "all"
},
"Name": "Attribution 1",
"Status": "completed"
}
],
"CreatedDate": "2024-01-15T10:30:00Z",
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"IId": 1,
"Name": "Q4 Attribution Set",
"Note": "Combined attribution analysis for Q4",
"Selected": true,
"Status": "complete"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Deactivate Attribution Set (/api/attribution-sets/deactivate_attribution_set_projects__team_id___project_id__attributionset__attributionset_id__activate_delete)
Deactivate the active attribution set.
Clears the active state of the specified attribution set. After this
call the project will have no active attribution set until a new one
is activated.
Path Parameters:
- attributionset_id: The IId of the attribution set to deactivate
Errors:
- 400 if the attribution set is not currently active
Response:
Updated attribution set with Selected=False.
## DELETE /api/projects/{team_id}/{project_id}/attributionset/{attributionset_id}/activate
Deactivate Attribution Set
Deactivate the active attribution set.
Clears the active state of the specified attribution set. After this
call the project will have no active attribution set until a new one
is activated.
Path Parameters:
- attributionset_id: The IId of the attribution set to deactivate
Errors:
- 400 if the attribution set is not currently active
Response:
Updated attribution set with Selected=False.
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Deactivate Attribution Set",
"description": "Deactivate the active attribution set.\n\nClears the active state of the specified attribution set. After this\ncall the project will have no active attribution set until a new one\nis activated.\n\nPath Parameters:\n - attributionset_id: The IId of the attribution set to deactivate\n\nErrors:\n - 400 if the attribution set is not currently active\n\nResponse:\n Updated attribution set with Selected=False.",
"operationId": "deactivate_attribution_set_projects__team_id___project_id__attributionset__attributionset_id__activate_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "attributionset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Provide attribution set IId or use 'active'",
"title": "Attributionset Id"
},
"description": "Provide attribution set IId or use 'active'"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths"
},
"Selected": {
"type": "boolean",
"title": "Selected",
"description": "Whether this is the active attribution set for the dashboard"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate",
"description": "Set creation timestamp"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the set"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Processing state: PENDING, PROCESSING, COMPLETE, or FAILED",
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState"
},
"CreationFilters": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Creationfilters",
"description": "Filters for auto-generating attributions (Country/Region)"
},
"Attributions": {
"items": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
},
"type": "array",
"title": "Attributions",
"description": "List of attribution jobs included in this set"
},
"DataSet": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
{
"type": "null"
}
],
"description": "Reference to the associated dataset"
}
},
"type": "object",
"required": [
"IId",
"Selected",
"CreatedDate",
"Status",
"Attributions"
],
"title": "AttributionSet",
"description": "Response schema for attribution sets (grouped attribution analyses).",
"examples": [
{
"Attributions": [
{
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00Z",
"IId": 1,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "Marketing Model",
"Region": "all"
},
"Name": "Attribution 1",
"Status": "completed"
}
],
"CreatedDate": "2024-01-15T10:30:00Z",
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Q4 Dataset",
"Selected": true,
"Status": "complete"
},
"IId": 1,
"Name": "Q4 Attribution Set",
"Note": "Combined attribution analysis for Q4",
"Selected": true,
"Status": "complete"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Attribution Set (/api/attribution-sets/download_attribution_set_projects__team_id___project_id__attributionset__attributionset_id__data_get)
Download aggregated attribution results as a CSV file.
Returns the merged effect data from all included attribution jobs.
The CSV shows how each input variable contributes to the target KPI
over time, enabling marketing mix analysis.
Prerequisites:
Attribution set Status must be COMPLETE.
Path Parameters:
- attributionset_id: The IId of the attribution set (or "active")
Query Parameters:
- result_filters: JSON filter expressions to subset results
Example: '{"Country": [["=", "USA"]], "Variable": [["contains", "tv"]]}'
Response:
CSV file stream with columns:
- Variable: Input variable slug
- Response: Target KPI slug
- Effect: Attributed impact value
- Date: Time period
- Quantile: Uncertainty percentile
- Group: Variable group category
- Type: Variable type
- Country/Region/Grouping: Geographic dimensions
Related:
- GET /attributionset/{attributionset_id}/variables: List available variables
- GET /attributionset/{attributionset_id}/parquet_data: Get Parquet format
## GET /api/projects/{team_id}/{project_id}/attributionset/{attributionset_id}/data
Download Attribution Set
Download aggregated attribution results as a CSV file.
Returns the merged effect data from all included attribution jobs.
The CSV shows how each input variable contributes to the target KPI
over time, enabling marketing mix analysis.
Prerequisites:
Attribution set Status must be COMPLETE.
Path Parameters:
- attributionset_id: The IId of the attribution set (or "active")
Query Parameters:
- result_filters: JSON filter expressions to subset results
Example: '{"Country": [["=", "USA"]], "Variable": [["contains", "tv"]]}'
Response:
CSV file stream with columns:
- Variable: Input variable slug
- Response: Target KPI slug
- Effect: Attributed impact value
- Date: Time period
- Quantile: Uncertainty percentile
- Group: Variable group category
- Type: Variable type
- Country/Region/Grouping: Geographic dimensions
Related:
- GET /attributionset/{attributionset_id}/variables: List available variables
- GET /attributionset/{attributionset_id}/parquet_data: Get Parquet format
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Download Attribution Set",
"description": "Download aggregated attribution results as a CSV file.\n\nReturns the merged effect data from all included attribution jobs.\nThe CSV shows how each input variable contributes to the target KPI\nover time, enabling marketing mix analysis.\n\nPrerequisites:\n Attribution set Status must be COMPLETE.\n\nPath Parameters:\n - attributionset_id: The IId of the attribution set (or \"active\")\n\nQuery Parameters:\n - result_filters: JSON filter expressions to subset results\n Example: '{\"Country\": [[\"=\", \"USA\"]], \"Variable\": [[\"contains\", \"tv\"]]}'\n\nResponse:\n CSV file stream with columns:\n - Variable: Input variable slug\n - Response: Target KPI slug\n - Effect: Attributed impact value\n - Date: Time period\n - Quantile: Uncertainty percentile\n - Group: Variable group category\n - Type: Variable type\n - Country/Region/Grouping: Geographic dimensions\n\nRelated:\n - GET /attributionset/{attributionset_id}/variables: List available variables\n - GET /attributionset/{attributionset_id}/parquet_data: Get Parquet format",
"operationId": "download_attribution_set_projects__team_id___project_id__attributionset__attributionset_id__data_get",
"parameters": [
{
"name": "attributionset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Provide attribution set IId or use 'active'",
"title": "Attributionset Id"
},
"description": "Provide attribution set IId or use 'active'"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "result_filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n Filter attribution result data rows.\n\n Examples:\n - By country: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - Multiple: result_filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"media\"]]}'\n - By response type: result_filters='{\"Response\": [[\"=\", \"sales\"]]}'\n - Combined: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n ",
"title": "Result Filters"
},
"description": "\n Filter attribution result data rows.\n\n Examples:\n - By country: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - Multiple: result_filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"media\"]]}'\n - By response type: result_filters='{\"Response\": [[\"=\", \"sales\"]]}'\n - Combined: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n "
},
{
"name": "output_format",
"in": "query",
"required": false,
"schema": {
"enum": [
"csv",
"parquet"
],
"type": "string",
"default": "csv",
"title": "Output Format"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"description": "Attribution set not in COMPLETE status - poll status first",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Attribution set not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution Set Group Metrics (/api/attribution-sets/get_attribution_set_group_metrics_projects__team_id___project_id__attributionset__attributionset_id__group_metrics_get)
Get effect/share rows from AttributionSetGroupMetrics for a completed set.
Returns rows for every effect Type (Total, Direct, Indirect) by default and
spans every modelling combination in the set; pass filters to narrow.
## GET /api/projects/{team_id}/{project_id}/attributionset/{attributionset_id}/group_metrics
Get Attribution Set Group Metrics
Get effect/share rows from AttributionSetGroupMetrics for a completed set.
Returns rows for every effect Type (Total, Direct, Indirect) by default and
spans every modelling combination in the set; pass filters to narrow.
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Get Attribution Set Group Metrics",
"description": "Get effect/share rows from AttributionSetGroupMetrics for a completed set.\n\nReturns rows for every effect Type (Total, Direct, Indirect) by default and\nspans every modelling combination in the set; pass filters to narrow.",
"operationId": "get_attribution_set_group_metrics_projects__team_id___project_id__attributionset__attributionset_id__group_metrics_get",
"parameters": [
{
"name": "attributionset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Provide attribution set IId or use 'active'",
"title": "Attributionset Id"
},
"description": "Provide attribution set IId or use 'active'"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By group: filters='{\"VarGroup\": [[\"=\", \"Media\"]]}'\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By group: filters='{\"VarGroup\": [[\"=\", \"Media\"]]}'\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n "
},
{
"name": "include_util_attr",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "If true, include RespUtilAttr (parsed util attributes) per row.",
"default": true,
"title": "Include Util Attr"
},
"description": "If true, include RespUtilAttr (parsed util attributes) per row."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"AttributionSetId": {
"type": "integer",
"title": "Attributionsetid"
},
"CombinationId": {
"type": "integer",
"title": "Combinationid"
},
"VarGroup": {
"type": "string",
"title": "Vargroup"
},
"RespIId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Respiid"
},
"Type": {
"type": "string",
"enum": [
"Direct",
"Indirect",
"Total"
],
"title": "AttrEffectTypes",
"description": "Attribution Effect Types."
},
"SumEffect": {
"type": "number",
"title": "Sumeffect"
},
"ShareOfEffect": {
"type": "number",
"title": "Shareofeffect"
},
"RespUtilAttr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"Id",
"AttributionSetId",
"CombinationId",
"VarGroup",
"RespIId",
"Type",
"SumEffect",
"ShareOfEffect"
],
"title": "AttributionSetGroupMetric",
"description": "Response schema for AttributionSetGroupMetrics — effect/share per group."
},
"title": "Response Get Attribution Set Group Metrics Projects Team Id Project Id Attributionset Attributionset Id Group Metrics Get"
}
}
}
},
"404": {
"description": "Attribution set not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution Set Variable Metrics (/api/attribution-sets/get_attribution_set_variable_metrics_projects__team_id___project_id__attributionset__attributionset_id__variable_metrics_get)
Get effect/share rows from AttributionSetVariableMetrics for a completed set.
Returns rows for every effect Type (Total, Direct, Indirect) by default and
spans every modelling combination in the set; pass filters to narrow.
## GET /api/projects/{team_id}/{project_id}/attributionset/{attributionset_id}/variable_metrics
Get Attribution Set Variable Metrics
Get effect/share rows from AttributionSetVariableMetrics for a completed set.
Returns rows for every effect Type (Total, Direct, Indirect) by default and
spans every modelling combination in the set; pass filters to narrow.
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Get Attribution Set Variable Metrics",
"description": "Get effect/share rows from AttributionSetVariableMetrics for a completed set.\n\nReturns rows for every effect Type (Total, Direct, Indirect) by default and\nspans every modelling combination in the set; pass filters to narrow.",
"operationId": "get_attribution_set_variable_metrics_projects__team_id___project_id__attributionset__attributionset_id__variable_metrics_get",
"parameters": [
{
"name": "attributionset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Provide attribution set IId or use 'active'",
"title": "Attributionset Id"
},
"description": "Provide attribution set IId or use 'active'"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "var_group",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by variable group (e.g. Media, CustomerExperience).",
"title": "Var Group"
},
"description": "Filter by variable group (e.g. Media, CustomerExperience)."
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By group: filters='{\"VarGroup\": [[\"=\", \"Media\"]]}'\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By group: filters='{\"VarGroup\": [[\"=\", \"Media\"]]}'\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n "
},
{
"name": "include_util_attr",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "If true, include VarUtilAttr/RespUtilAttr (parsed util attributes) per row.",
"default": true,
"title": "Include Util Attr"
},
"description": "If true, include VarUtilAttr/RespUtilAttr (parsed util attributes) per row."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"AttributionSetId": {
"type": "integer",
"title": "Attributionsetid"
},
"CombinationId": {
"type": "integer",
"title": "Combinationid"
},
"VarIId": {
"type": "integer",
"title": "Variid"
},
"VarSlug": {
"type": "string",
"title": "Varslug"
},
"VarGroup": {
"type": "string",
"title": "Vargroup"
},
"RespIId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Respiid"
},
"Type": {
"type": "string",
"enum": [
"Direct",
"Indirect",
"Total"
],
"title": "AttrEffectTypes",
"description": "Attribution Effect Types."
},
"SumEffect": {
"type": "number",
"title": "Sumeffect"
},
"ShareOfEffect": {
"type": "number",
"title": "Shareofeffect"
},
"VarUtilAttr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
]
},
"RespUtilAttr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"Id",
"AttributionSetId",
"CombinationId",
"VarIId",
"VarSlug",
"VarGroup",
"RespIId",
"Type",
"SumEffect",
"ShareOfEffect"
],
"title": "AttributionSetVariableMetric",
"description": "Response schema for AttributionSetVariableMetrics — effect/share per variable."
},
"title": "Response Get Attribution Set Variable Metrics Projects Team Id Project Id Attributionset Attributionset Id Variable Metrics Get"
}
}
}
},
"404": {
"description": "Attribution set not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution Set Totals (/api/attribution-sets/get_attribution_set_totals_projects__team_id___project_id__attributionset__attributionset_id__totals_get)
Get TotalEffect rows from AttributionSetTotals for a completed set.
Returns rows for every effect Type (Total, Direct, Indirect) by default and
spans every modelling combination in the set; pass filters to narrow.
## GET /api/projects/{team_id}/{project_id}/attributionset/{attributionset_id}/totals
Get Attribution Set Totals
Get TotalEffect rows from AttributionSetTotals for a completed set.
Returns rows for every effect Type (Total, Direct, Indirect) by default and
spans every modelling combination in the set; pass filters to narrow.
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Get Attribution Set Totals",
"description": "Get TotalEffect rows from AttributionSetTotals for a completed set.\n\nReturns rows for every effect Type (Total, Direct, Indirect) by default and\nspans every modelling combination in the set; pass filters to narrow.",
"operationId": "get_attribution_set_totals_projects__team_id___project_id__attributionset__attributionset_id__totals_get",
"parameters": [
{
"name": "attributionset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Provide attribution set IId or use 'active'",
"title": "Attributionset Id"
},
"description": "Provide attribution set IId or use 'active'"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - Grand totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - Grand totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n "
},
{
"name": "include_util_attr",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "If true, include RespUtilAttr (parsed util attributes) per row.",
"default": true,
"title": "Include Util Attr"
},
"description": "If true, include RespUtilAttr (parsed util attributes) per row."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"AttributionSetId": {
"type": "integer",
"title": "Attributionsetid"
},
"CombinationId": {
"type": "integer",
"title": "Combinationid"
},
"RespIId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Respiid"
},
"Type": {
"type": "string",
"enum": [
"Direct",
"Indirect",
"Total"
],
"title": "AttrEffectTypes",
"description": "Attribution Effect Types."
},
"TotalEffect": {
"type": "number",
"title": "Totaleffect"
},
"RespUtilAttr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"Id",
"AttributionSetId",
"CombinationId",
"RespIId",
"Type",
"TotalEffect"
],
"title": "AttributionSetTotal",
"description": "Response schema for AttributionSetTotals — shared TotalEffect denominator."
},
"title": "Response Get Attribution Set Totals Projects Team Id Project Id Attributionset Attributionset Id Totals Get"
}
}
}
},
"404": {
"description": "Attribution set not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution Set Group Roi (/api/attribution-sets/get_attribution_set_group_roi_projects__team_id___project_id__attributionset__attributionset_id__group_roi_get)
Get investment/ROI rows from AttributionSetGroupROI for a completed set.
Returns rows for every effect Type (Total, Direct, Indirect) by default and
spans every modelling combination in the set; pass filters to narrow.
## GET /api/projects/{team_id}/{project_id}/attributionset/{attributionset_id}/group_roi
Get Attribution Set Group Roi
Get investment/ROI rows from AttributionSetGroupROI for a completed set.
Returns rows for every effect Type (Total, Direct, Indirect) by default and
spans every modelling combination in the set; pass filters to narrow.
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Get Attribution Set Group Roi",
"description": "Get investment/ROI rows from AttributionSetGroupROI for a completed set.\n\nReturns rows for every effect Type (Total, Direct, Indirect) by default and\nspans every modelling combination in the set; pass filters to narrow.",
"operationId": "get_attribution_set_group_roi_projects__team_id___project_id__attributionset__attributionset_id__group_roi_get",
"parameters": [
{
"name": "attributionset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Provide attribution set IId or use 'active'",
"title": "Attributionset Id"
},
"description": "Provide attribution set IId or use 'active'"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By group: filters='{\"VarGroup\": [[\"=\", \"Media\"]]}'\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - High ROI: filters='{\"EffectROI\": [[\">=\", \"2\"]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By group: filters='{\"VarGroup\": [[\"=\", \"Media\"]]}'\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - High ROI: filters='{\"EffectROI\": [[\">=\", \"2\"]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n "
},
{
"name": "include_util_attr",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "If true, include RespUtilAttr (parsed util attributes) per row.",
"default": true,
"title": "Include Util Attr"
},
"description": "If true, include RespUtilAttr (parsed util attributes) per row."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"AttributionSetId": {
"type": "integer",
"title": "Attributionsetid"
},
"CombinationId": {
"type": "integer",
"title": "Combinationid"
},
"VarGroup": {
"type": "string",
"title": "Vargroup"
},
"RespIId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Respiid"
},
"Type": {
"type": "string",
"enum": [
"Direct",
"Indirect",
"Total"
],
"title": "AttrEffectTypes",
"description": "Attribution Effect Types."
},
"Investment": {
"type": "number",
"title": "Investment"
},
"CPX": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Cpx"
},
"EffectROI": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Effectroi"
},
"RevenueROI": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Revenueroi"
},
"ProfitROI": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Profitroi"
},
"RespUtilAttr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"Id",
"AttributionSetId",
"CombinationId",
"VarGroup",
"RespIId",
"Type",
"Investment",
"CPX",
"EffectROI",
"RevenueROI",
"ProfitROI"
],
"title": "AttributionSetGroupROIMetric",
"description": "Response schema for AttributionSetGroupROI — investment/ROI for Media/CX groups."
},
"title": "Response Get Attribution Set Group Roi Projects Team Id Project Id Attributionset Attributionset Id Group Roi Get"
}
}
}
},
"404": {
"description": "Attribution set not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Attribution Set Variable Roi (/api/attribution-sets/get_attribution_set_variable_roi_projects__team_id___project_id__attributionset__attributionset_id__variable_roi_get)
Get investment/ROI rows from AttributionSetVariableROI for a completed set.
Returns rows for every effect Type (Total, Direct, Indirect) by default and
spans every modelling combination in the set; pass filters to narrow.
## GET /api/projects/{team_id}/{project_id}/attributionset/{attributionset_id}/variable_roi
Get Attribution Set Variable Roi
Get investment/ROI rows from AttributionSetVariableROI for a completed set.
Returns rows for every effect Type (Total, Direct, Indirect) by default and
spans every modelling combination in the set; pass filters to narrow.
```json
{
"tags": [
"Attribution Sets"
],
"summary": "Get Attribution Set Variable Roi",
"description": "Get investment/ROI rows from AttributionSetVariableROI for a completed set.\n\nReturns rows for every effect Type (Total, Direct, Indirect) by default and\nspans every modelling combination in the set; pass filters to narrow.",
"operationId": "get_attribution_set_variable_roi_projects__team_id___project_id__attributionset__attributionset_id__variable_roi_get",
"parameters": [
{
"name": "attributionset_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
}
],
"description": "Provide attribution set IId or use 'active'",
"title": "Attributionset Id"
},
"description": "Provide attribution set IId or use 'active'"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - High ROI: filters='{\"EffectROI\": [[\">=\", \"2\"]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - Totals only: filters='{\"RespId\": [[\"is\", null]]}'\n - High ROI: filters='{\"EffectROI\": [[\">=\", \"2\"]]}'\n - By effect type: filters='{\"Type\": [[\"=\", \"Total\"]]}'\n "
},
{
"name": "include_util_attr",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "If true, include VarUtilAttr/RespUtilAttr (parsed util attributes) per row.",
"default": true,
"title": "Include Util Attr"
},
"description": "If true, include VarUtilAttr/RespUtilAttr (parsed util attributes) per row."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"AttributionSetId": {
"type": "integer",
"title": "Attributionsetid"
},
"CombinationId": {
"type": "integer",
"title": "Combinationid"
},
"VarIId": {
"type": "integer",
"title": "Variid"
},
"RespIId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Respiid"
},
"Type": {
"type": "string",
"enum": [
"Direct",
"Indirect",
"Total"
],
"title": "AttrEffectTypes",
"description": "Attribution Effect Types."
},
"Investment": {
"type": "number",
"title": "Investment"
},
"CPX": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Cpx"
},
"EffectROI": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Effectroi"
},
"RevenueROI": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Revenueroi"
},
"ProfitROI": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Profitroi"
},
"VarUtilAttr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
]
},
"RespUtilAttr": {
"anyOf": [
{
"properties": {
"Product": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Product"
},
"Media": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Media"
},
"Campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Campaign"
},
"Metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Metric"
},
"Competitor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Competitor"
},
"Event": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Event"
},
"Channel": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Channel"
},
"Brand": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Brand"
},
"Indicator": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Indicator"
},
"Variable": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Variable"
},
"Format": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Format"
},
"Device": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Device"
},
"TargetGroup": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Targetgroup"
},
"Creative": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative"
},
"Category": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Category"
}
},
"type": "object",
"title": "_UtilAttr"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"Id",
"AttributionSetId",
"CombinationId",
"VarIId",
"RespIId",
"Type",
"Investment",
"CPX",
"EffectROI",
"RevenueROI",
"ProfitROI"
],
"title": "AttributionSetVariableROIMetric",
"description": "Response schema for AttributionSetVariableROI — investment/ROI for Media/CX variables."
},
"title": "Response Get Attribution Set Variable Roi Projects Team Id Project Id Attributionset Attributionset Id Variable Roi Get"
}
}
}
},
"404": {
"description": "Attribution set not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Optimizations (/api/optimizations/list_optimizations_projects__team_id___project_id__optimizations_get)
List all optimization jobs in the project with optional filtering.
Returns a paginated list of optimization jobs, useful for monitoring
job status and reviewing optimization history.
Query Parameters:
- filters: JSON filter expressions to narrow results
Example: '{"Status": [["=", "COMPLETED"]]}'
Response:
Paginated list of optimization jobs.
Related:
- GET /optimizations/{optimization_id}: Get full details
- POST /optimizations: Create a new optimization job
## GET /api/projects/{team_id}/{project_id}/optimizations
List Optimizations
List all optimization jobs in the project with optional filtering.
Returns a paginated list of optimization jobs, useful for monitoring
job status and reviewing optimization history.
Query Parameters:
- filters: JSON filter expressions to narrow results
Example: '{"Status": [["=", "COMPLETED"]]}'
Response:
Paginated list of optimization jobs.
Related:
- GET /optimizations/{optimization_id}: Get full details
- POST /optimizations: Create a new optimization job
```json
{
"tags": [
"Optimizations"
],
"summary": "List Optimizations",
"description": "List all optimization jobs in the project with optional filtering.\n\nReturns a paginated list of optimization jobs, useful for monitoring\njob status and reviewing optimization history.\n\nQuery Parameters:\n - filters: JSON filter expressions to narrow results\n Example: '{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n\nResponse:\n Paginated list of optimization jobs.\n\nRelated:\n - GET /optimizations/{optimization_id}: Get full details\n - POST /optimizations: Create a new optimization job",
"operationId": "list_optimizations_projects__team_id___project_id__optimizations_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Multiple filters create OR logic.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By model ID: filters='{\"Model.IId\": [[\"=\", \"42\"]]}'\n - Recent optimizations: filters='{\"Date\": [[\">=\", \"2024-10-01\"]]}'\n - By improvement: filters='{\"Improvement\": [[\">=\", \"0.1\"]]}'\n - High performers: filters='{\"TargetResult\": [[\">=\", \"100000\"]]}'\n - Sort by improvement: filters='{\"Improvement\": [[\"orderby\", \"desc\"]]}'\n - Name search: filters='{\"Name\": [[\"similarity\", \"budget optimization\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby, similarity\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Multiple filters create OR logic.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By model ID: filters='{\"Model.IId\": [[\"=\", \"42\"]]}'\n - Recent optimizations: filters='{\"Date\": [[\">=\", \"2024-10-01\"]]}'\n - By improvement: filters='{\"Improvement\": [[\">=\", \"0.1\"]]}'\n - High performers: filters='{\"TargetResult\": [[\">=\", \"100000\"]]}'\n - Sort by improvement: filters='{\"Improvement\": [[\"orderby\", \"desc\"]]}'\n - Name search: filters='{\"Name\": [[\"similarity\", \"budget optimization\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby, similarity\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"Model": {
"description": "Reference to the trained model used for optimization",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Params": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Params",
"description": "Full optimization configuration parameters"
},
"TargetResult": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Targetresult",
"description": "Final objective value achieved by optimization"
},
"BaselineTarget": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Baselinetarget",
"description": "Target goal value (for goal-seek optimizations)"
},
"BaselineTargetResult": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Baselinetargetresult",
"description": "Objective value at baseline (before optimization)"
},
"Improvement": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Improvement",
"description": "Percent improvement: (Target - Baseline) / Baseline"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Date",
"Model"
],
"title": "OptimizationJobs",
"description": "Response schema for optimization jobs listing and summary views.",
"examples": [
{
"BaselineTarget": 100000,
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"Improvement": 0.5,
"JobId": 456,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Q4 Budget Optimization",
"Note": "Optimizing marketing spend for Q4",
"Status": "completed",
"TargetResult": 150000
}
]
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[OptimizationJobs]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Submit Optiomization (/api/optimizations/submit_optiomization_projects__team_id___project_id__optimizations_post)
Submit an optimization job to find optimal variable allocations.
Use optimization to automatically determine the best allocation of input
variables (e.g., marketing budget across channels) to maximize or achieve
a target for an objective (e.g., maximize sales, hit revenue goal) while
respecting constraints.
Workflow:
1. Ensure you have a trained model (see POST /build/model)
2. Define optimization targets (maximize, goal-seek)
3. Specify variables to optimize (opt_nodes)
4. Add constraints (boundary, equality/inequality)
5. Submit optimization with this endpoint
6. Poll GET /optimizations/{optimization_id} until Status is COMPLETED
7. Download optimal allocation via GET /optimizations/{optimization_id}/data
Response:
Returns the created optimization job. Poll status until COMPLETED.
Related:
- GET /optimizations/{optimization_id}: Poll job status
- GET /optimizations/{optimization_id}/data: Download optimal allocation
- POST /optimizations/{optimization_id}/simulate: Run simulation with results
## POST /api/projects/{team_id}/{project_id}/optimizations
Submit Optiomization
Submit an optimization job to find optimal variable allocations.
Use optimization to automatically determine the best allocation of input
variables (e.g., marketing budget across channels) to maximize or achieve
a target for an objective (e.g., maximize sales, hit revenue goal) while
respecting constraints.
Workflow:
1. Ensure you have a trained model (see POST /build/model)
2. Define optimization targets (maximize, goal-seek)
3. Specify variables to optimize (opt_nodes)
4. Add constraints (boundary, equality/inequality)
5. Submit optimization with this endpoint
6. Poll GET /optimizations/{optimization_id} until Status is COMPLETED
7. Download optimal allocation via GET /optimizations/{optimization_id}/data
Response:
Returns the created optimization job. Poll status until COMPLETED.
Related:
- GET /optimizations/{optimization_id}: Poll job status
- GET /optimizations/{optimization_id}/data: Download optimal allocation
- POST /optimizations/{optimization_id}/simulate: Run simulation with results
```json
{
"tags": [
"Optimizations"
],
"summary": "Submit Optiomization",
"description": "Submit an optimization job to find optimal variable allocations.\n\nUse optimization to automatically determine the best allocation of input\nvariables (e.g., marketing budget across channels) to maximize or achieve\na target for an objective (e.g., maximize sales, hit revenue goal) while\nrespecting constraints.\n\nWorkflow:\n 1. Ensure you have a trained model (see POST /build/model)\n 2. Define optimization targets (maximize, goal-seek)\n 3. Specify variables to optimize (opt_nodes)\n 4. Add constraints (boundary, equality/inequality)\n 5. Submit optimization with this endpoint\n 6. Poll GET /optimizations/{optimization_id} until Status is COMPLETED\n 7. Download optimal allocation via GET /optimizations/{optimization_id}/data\n\nResponse:\n Returns the created optimization job. Poll status until COMPLETED.\n\nRelated:\n - GET /optimizations/{optimization_id}: Poll job status\n - GET /optimizations/{optimization_id}/data: Download optimal allocation\n - POST /optimizations/{optimization_id}/simulate: Run simulation with results",
"operationId": "submit_optiomization_projects__team_id___project_id__optimizations_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"targets": {
"description": "Optimization objective: what to maximize/minimize, target KPI variables, risk tolerance, and optional goal value. Use 'directions' to set per-node optimization direction.",
"properties": {
"goal": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Goal"
},
"relative": {
"type": "boolean",
"title": "Relative",
"default": false
},
"risk": {
"type": "number",
"exclusiveMaximum": 0.99,
"exclusiveMinimum": 0.01,
"title": "Risk",
"default": 0.5
},
"directions": {
"items": {
"properties": {
"op": {
"type": "string",
"enum": [
"Minimize",
"Maximize",
"Neutral"
],
"title": "DirectionOP",
"description": "Equality and Inquality operators."
},
"variable": {
"type": "string",
"title": "Variable",
"description": "variable name"
}
},
"type": "object",
"required": [
"op",
"variable"
],
"title": "Direction",
"description": "Define node directions."
},
"type": "array",
"title": "Directions",
"description": "Node directions"
},
"maximize": {
"type": "boolean",
"title": "Maximize",
"description": "Whether to maximize or minimize the targets ",
"default": true
},
"variables": {
"anyOf": [
{
"items": {
"properties": {
"dates": {
"anyOf": [
{
"items": {
"type": "string",
"format": "date-time"
},
"type": "array"
},
{
"properties": {
"start_date": {
"type": "string",
"format": "date-time",
"title": "Start Date"
},
"end_date": {
"type": "string",
"format": "date-time",
"title": "End Date"
}
},
"type": "object",
"required": [
"start_date",
"end_date"
],
"title": "DateRange",
"description": "Date range selector."
},
{
"type": "null"
}
],
"title": "Dates",
"description": "Select all dates by set to None, select specific dates, or select range"
},
"variable": {
"type": "string",
"title": "Variable",
"description": "variable"
}
},
"type": "object",
"required": [
"variable"
],
"title": "Variable",
"description": "Select Variable."
},
"type": "array",
"minItems": 1
},
{
"type": "null"
}
],
"title": "Variables",
"description": "list of target variables"
},
"op": {
"anyOf": [
{
"type": "string",
"enum": [
"sum"
],
"title": "OptimizationOp",
"description": "Optimization Operators."
},
{
"type": "null"
}
],
"description": "How the target 'variables' are aggregated. Only 'sum' is supported, which is also the default.",
"default": "sum"
},
"transform": {
"type": "string",
"enum": [
"identity",
"revenue",
"profit"
],
"title": "Transform",
"default": "identity"
}
},
"type": "object",
"title": "OptimizationTargets"
},
"updated_values": {
"anyOf": [
{
"additionalProperties": {
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable"
},
"update": {
"anyOf": [
{
"items": {
"prefixItems": [
{
"type": "string",
"format": "date-time",
"title": "Date"
},
{
"type": "number",
"title": "Value"
}
],
"type": "array",
"maxItems": 2,
"minItems": 2
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Update"
}
},
"type": "object",
"required": [
"variable",
"update"
],
"title": "UpdatedVariable",
"description": "Schema for schenario updated variabls values."
},
"type": "array"
},
"propertyNames": {
"const": "scenario"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Updated Values",
"description": "Optional scenario variable modifications for baseline and scenario. Dict mapping scenario names to {variable, update} lists."
},
"opt_nodes": {
"items": {
"type": "string"
},
"type": "array",
"title": "Opt Nodes",
"description": "Variable slugs that the optimizer can adjust. These are the 'levers' (e.g., media spend variables) that optimization will tune."
},
"boundary_constraint": {
"anyOf": [
{
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable",
"description": "variable name"
},
"min": {
"anyOf": [
{
"items": {
"type": "number"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Min",
"description": "Lower bound. One value per date step in the optimization window ('data_start_date' to 'data_end_date', or 'dates_subset' when given)."
},
"max": {
"anyOf": [
{
"items": {
"type": "number"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Max",
"description": "Upper bound. One value per date step in the optimization window ('data_start_date' to 'data_end_date', or 'dates_subset' when given)."
},
"threshold_min": {
"anyOf": [
{
"items": {
"type": "number"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Threshold Min",
"description": "Soft lower bound, only allowed together with 'min'. One value per date step in the optimization window ('data_start_date' to 'data_end_date', or 'dates_subset' when given)."
},
"threshold_max": {
"anyOf": [
{
"items": {
"type": "number"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Threshold Max",
"description": "Soft upper bound, only allowed together with 'max'. One value per date step in the optimization window ('data_start_date' to 'data_end_date', or 'dates_subset' when given)."
}
},
"type": "object",
"required": [
"variable"
],
"title": "OptimizationBoundaryConstraint",
"description": "Define boudary constraint for optimization."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Boundary Constraint",
"description": "Per-variable min/max bounds constraining optimizer adjustments. Use threshold_min/threshold_max for soft constraints."
},
"equality_inequality_constraints": {
"anyOf": [
{
"items": {
"properties": {
"constraint": {
"properties": {
"variables": {
"items": {
"properties": {
"dates": {
"anyOf": [
{
"items": {
"type": "string",
"format": "date-time"
},
"type": "array"
},
{
"properties": {
"start_date": {
"type": "string",
"format": "date-time",
"title": "Start Date"
},
"end_date": {
"type": "string",
"format": "date-time",
"title": "End Date"
}
},
"type": "object",
"required": [
"start_date",
"end_date"
],
"title": "DateRange",
"description": "Date range selector."
},
{
"type": "null"
}
],
"title": "Dates",
"description": "Select all dates by set to None, select specific dates, or select range"
},
"variable": {
"type": "string",
"title": "Variable",
"description": "variable"
}
},
"type": "object",
"required": [
"variable"
],
"title": "Variable",
"description": "Select Variable."
},
"type": "array",
"minItems": 1,
"title": "Variables",
"description": "list of target variables"
},
"op": {
"description": "target operators",
"type": "string",
"enum": [
"sum"
],
"title": "OptimizationOp"
}
},
"type": "object",
"required": [
"variables",
"op"
],
"title": "Code",
"description": "Code body."
},
"op": {
"type": "string",
"enum": [
"<=",
">=",
"=="
],
"title": "EqualityOP",
"description": "Equality and Inquality operators."
},
"value": {
"type": "number",
"title": "Value"
}
},
"type": "object",
"required": [
"constraint",
"op",
"value"
],
"title": "EqualityInequalityConstraints",
"description": "Defines equality and inequality constraint."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Equality Inequality Constraints",
"description": "Cross-variable constraints (e.g., sum of budgets <= total). Supports <=, >=, == operators on variable aggregations."
},
"init_value": {
"anyOf": [
{
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable",
"description": "variable name"
},
"value": {
"type": "string",
"enum": [
"random",
"min",
"max",
"mean",
"median",
"range10",
"range20",
"range30",
"range40",
"range60",
"range70",
"range80",
"range90"
],
"title": "InitValues",
"description": "Init value types."
}
},
"type": "object",
"required": [
"variable",
"value"
],
"title": "InitValue",
"description": "Define init values."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Init Value",
"description": "Starting point strategy for each optimizable variable. Options include 'random', 'min', 'max', 'mean', 'median', or 'rangeN' percentiles."
},
"samples": {
"type": "integer",
"title": "The samples",
"description": "Hom many subsamples to draw from the posterior distribution. The higher number of samples the better the uncertainty estimation becomes but it also takes longer to run.",
"default": 10
},
"epochs": {
"type": "integer",
"title": "Epochs",
"description": "Number of optimization iterations.",
"default": 1000
},
"lr": {
"type": "number",
"title": "Lr",
"description": "Learning rate for gradient descent.",
"default": 0.1
},
"lr_decay": {
"type": "number",
"title": "Lr Decay",
"description": "Learning rate decay factor applied at lr_decay_step.",
"default": 0.25
},
"lr_decay_step": {
"type": "integer",
"title": "Lr Decay Step",
"description": "Epochs between learning rate decay applications.",
"default": 250
},
"grad_clip": {
"type": "number",
"title": "Grad Clip",
"description": "Gradient clipping threshold for training stability.",
"default": 1
},
"data_start_date": {
"type": "string",
"format": "date-time",
"title": "Data Start Date",
"description": "Start of the data range for optimization. ISO 8601 format."
},
"data_end_date": {
"type": "string",
"format": "date-time",
"title": "Data End Date",
"description": "End of the data range for optimization. ISO 8601 format."
},
"dates_subset": {
"anyOf": [
{
"properties": {
"dates": {
"anyOf": [
{
"items": {
"type": "string",
"format": "date-time"
},
"type": "array"
},
{
"properties": {
"start_date": {
"type": "string",
"format": "date-time",
"title": "Start Date"
},
"end_date": {
"type": "string",
"format": "date-time",
"title": "End Date"
}
},
"type": "object",
"required": [
"start_date",
"end_date"
],
"title": "DateRange",
"description": "Date range selector."
},
{
"type": "null"
}
],
"title": "Dates",
"description": "Select all dates by set to None, select specific dates, or select range"
}
},
"type": "object",
"title": "DateSelector",
"description": "Dates selector."
},
{
"type": "null"
}
],
"description": "Optional subset of dates within the data range to optimize over. Use for excluding holidays or focusing on specific periods."
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
},
"model_id": {
"type": "integer",
"title": "Model Id",
"description": "IId of the trained model to use. Model must have Status=COMPLETED. Get available models from GET /models endpoint."
},
"return_best_loss": {
"type": "boolean",
"title": "Return Best Loss",
"description": "If True, returns the solution with best loss even if constraints are slightly violated (within allowed percentage).",
"default": true
},
"best_loss_allowed_pct_violation": {
"type": "number",
"title": "Best Loss Allowed Pct Violation",
"description": "Maximum allowed constraint violation percentage (0-1) when return_best_loss=True. 0.5 = 50% violation tolerance.",
"default": 0.5
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
},
"attribution": {
"anyOf": [
{
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"samples": {
"type": "integer",
"title": "The samples",
"description": "Hom many subsamples to draw from the posterior distribution. The higher number of samples the better the uncertainty estimation becomes but it also takes longer to run.",
"default": 20
},
"baseline": {
"anyOf": [
{
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable",
"description": "Variable slug."
},
"baseline": {
"type": "number",
"title": "Baseline",
"description": "Set baseline."
}
},
"type": "object",
"required": [
"variable",
"baseline"
],
"title": "ReferencePointBaseline",
"description": "Attribution job baseline."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Baseline"
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
},
"quantiles": {
"anyOf": [
{
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Quantiles",
"default": [
1,
25,
50,
75,
99
]
},
"referece_point_fallback": {
"anyOf": [
{
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback",
"description": "Attribution's reference point fallback."
},
{
"type": "null"
}
],
"description": "Reference point fallback.",
"default": "Min"
},
"predicted_targets_as_data": {
"type": "boolean",
"title": "Predicted Targets As Data",
"description": "Set predicted targets as data.",
"default": true
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Optional integer seed. If omitted, the chained attribution inherits the parent job's seed."
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Start Date",
"description": "The first date in the date range used to select data from the dataset"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "End Date",
"description": "The last date in the date range used to select data from the dataset."
}
},
"type": "object",
"title": "AttributionAfterJob",
"description": "Run attribution after a job."
},
{
"type": "null"
}
],
"description": "Auto-runs attribution analysis after optimization completes. Quantifies variable contributions to the optimized result."
},
"additional_config": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Additional Config",
"description": "UI-specific configuration passed through to frontend display."
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Optional integer seed for reproducible runs. If omitted, the server generates a random seed."
},
"validate_limits": {
"type": "boolean",
"title": "Validate Limits",
"description": "Validate values against per-variable min/max limits.",
"default": false
}
},
"type": "object",
"required": [
"targets",
"opt_nodes",
"data_start_date",
"data_end_date",
"model_id"
],
"title": "OptimizationPost",
"description": "Request body for creating a budget/resource optimization job.",
"examples": [
{
"attribution": {
"name": "Optimization Attribution",
"priority": 30,
"quantiles": [
1,
25,
50,
75,
99
],
"samples": 20
},
"best_loss_allowed_pct_violation": 0.5,
"boundary_constraint": [
{
"max": [
50000,
50000,
50000
],
"min": [
5000,
5000,
5000
],
"variable": "tv_spend"
},
{
"max": [
30000,
30000,
30000
],
"min": [
2000,
2000,
2000
],
"variable": "digital_spend"
}
],
"data_end_date": "2024-12-31T00:00:00Z",
"data_start_date": "2024-01-01T00:00:00Z",
"dataset_id": "active",
"epochs": 1000,
"equality_inequality_constraints": [
{
"constraint": {
"op": "sum",
"variables": [
{
"variable": "tv_spend"
},
{
"variable": "digital_spend"
}
]
},
"op": "<=",
"value": 100000
}
],
"grad_clip": 1,
"init_value": [
{
"value": "mean",
"variable": "tv_spend"
},
{
"value": "mean",
"variable": "digital_spend"
}
],
"lr": 0.1,
"lr_decay": 0.25,
"lr_decay_step": 250,
"model_id": 1,
"name": "Q4 Budget Optimization",
"note": "Optimize media allocation for maximum sales",
"opt_nodes": [
"tv_spend",
"digital_spend",
"print_spend"
],
"priority": 30,
"return_best_loss": true,
"samples": 10,
"targets": {
"directions": [
{
"op": "Maximize",
"variable": "sales_units"
}
],
"maximize": true,
"op": "sum",
"relative": false,
"risk": 0.5,
"transform": "identity",
"variables": [
{
"variable": "sales_units"
}
]
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"Model": {
"description": "Reference to the trained model used for optimization",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Params": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Params",
"description": "Full optimization configuration parameters"
},
"TargetResult": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Targetresult",
"description": "Final objective value achieved by optimization"
},
"BaselineTarget": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Baselinetarget",
"description": "Target goal value (for goal-seek optimizations)"
},
"BaselineTargetResult": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Baselinetargetresult",
"description": "Objective value at baseline (before optimization)"
},
"Improvement": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Improvement",
"description": "Percent improvement: (Target - Baseline) / Baseline"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Date",
"Model"
],
"title": "OptimizationJobs",
"description": "Response schema for optimization jobs listing and summary views.",
"examples": [
{
"BaselineTarget": 100000,
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"Improvement": 0.5,
"JobId": 456,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Q4 Budget Optimization",
"Note": "Optimizing marketing spend for Q4",
"Status": "completed",
"TargetResult": 150000
}
]
}
}
}
},
"400": {
"description": "Invalid optimization request: model not found, opt_nodes variables not in model/dataset, invalid constraints (boundary, equality/inequality), invalid target configuration, or date range outside dataset",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Project is in read-only state",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Bulk Delete Optimizations (/api/optimizations/bulk_delete_optimizations_projects__team_id___project_id__optimizations_delete)
Bulk delete optimization jobs matching the given filters.
Marks all matching jobs for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
## DELETE /api/projects/{team_id}/{project_id}/optimizations
Bulk Delete Optimizations
Bulk delete optimization jobs matching the given filters.
Marks all matching jobs for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
```json
{
"tags": [
"Optimizations"
],
"summary": "Bulk Delete Optimizations",
"description": "Bulk delete optimization jobs matching the given filters.\n\nMarks all matching jobs for deletion and publishes delete messages to\nRabbitMQ concurrently in the background via a single DB round-trip each.",
"operationId": "bulk_delete_optimizations_projects__team_id___project_id__optimizations_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By date: filters='{\"Date\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"USA_Model\"]]}'\n - By date: filters='{\"Date\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n "
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Optimization (/api/optimizations/get_optimization_projects__team_id___project_id__optimizations__optimization_id__get)
Get detailed information about a specific optimization job.
Use this endpoint to check job status, view optimization configuration,
and review results. Poll until Status is COMPLETED before downloading
optimal allocations.
Path Parameters:
- optimization_id: The IId of the optimization job
Response:
Detailed optimization job with results and constraint information.
Related:
- GET /optimizations/{optimization_id}/data: Download optimal allocation
- POST /optimizations/{optimization_id}/simulate: Run simulation with results
## GET /api/projects/{team_id}/{project_id}/optimizations/{optimization_id}
Get Optimization
Get detailed information about a specific optimization job.
Use this endpoint to check job status, view optimization configuration,
and review results. Poll until Status is COMPLETED before downloading
optimal allocations.
Path Parameters:
- optimization_id: The IId of the optimization job
Response:
Detailed optimization job with results and constraint information.
Related:
- GET /optimizations/{optimization_id}/data: Download optimal allocation
- POST /optimizations/{optimization_id}/simulate: Run simulation with results
```json
{
"tags": [
"Optimizations"
],
"summary": "Get Optimization",
"description": "Get detailed information about a specific optimization job.\n\nUse this endpoint to check job status, view optimization configuration,\nand review results. Poll until Status is COMPLETED before downloading\noptimal allocations.\n\nPath Parameters:\n - optimization_id: The IId of the optimization job\n\nResponse:\n Detailed optimization job with results and constraint information.\n\nRelated:\n - GET /optimizations/{optimization_id}/data: Download optimal allocation\n - POST /optimizations/{optimization_id}/simulate: Run simulation with results",
"operationId": "get_optimization_projects__team_id___project_id__optimizations__optimization_id__get",
"parameters": [
{
"name": "optimization_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide optimization IId",
"title": "Optimization Id"
},
"description": "Provide optimization IId"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"Task": {
"anyOf": [
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"Topic": {
"type": "string",
"enum": [
"ATTRIBUTIONSET",
"ATTRIBUTIONJOB",
"SIMULATIONJOB",
"PREDICTIONJOB",
"TRAINJOB",
"DATASET",
"DATAUPLOAD",
"GRAPHCONSTRUCT",
"GENERAL",
"OPTIMIZATIONJOB",
"RESPOSNSECURVEJOB",
"PRIORPOSTERIORJOB",
"EXCELJOB",
"GRAPHBASIC",
"FEATUREIMPORTANCE",
"GRAPHSYNERGY"
],
"title": "TaskTopics",
"description": "Task topics."
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"Id",
"Config",
"Topic",
"Status"
],
"title": "Task",
"description": "Reference task."
},
{
"type": "null"
}
]
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"Model": {
"description": "Reference to the trained model used for optimization",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Params": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Params",
"description": "Full optimization configuration parameters"
},
"TargetResult": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Targetresult",
"description": "Final objective value achieved by optimization"
},
"BaselineTarget": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Baselinetarget",
"description": "Target goal value (for goal-seek optimizations)"
},
"BaselineTargetResult": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Baselinetargetresult",
"description": "Objective value at baseline (before optimization)"
},
"Improvement": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Improvement",
"description": "Percentage improvement over baseline"
},
"Loss": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Loss",
"description": "Final objective function loss value"
},
"ConstraintLoss": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Constraintloss",
"description": "Penalty from constraint violations"
},
"ConstraintViolations": {
"anyOf": [
{
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"Value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Value"
},
"Violation": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Violation"
},
"Constraint": {
"title": "Constraint"
}
},
"type": "object",
"required": [
"Id",
"Constraint"
],
"title": "ConstraintViolations",
"description": "Referenche schema for ConstraintViolations."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Constraintviolations",
"description": "List of violated constraints with details"
},
"ConstraintViolation": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Constraintviolation",
"description": "Total constraint violation magnitude"
},
"AdditionalConfig": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Additionalconfig",
"description": "Additional optimization configuration"
},
"Seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Seed used for reproducible runs"
},
"SimulationJob": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"IsFromOptimization": {
"type": "boolean",
"title": "Isfromoptimization",
"description": "Whether this simulation was submitted by an optimization job.",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"IsFromOptimization"
],
"title": "SimulationJobsRef",
"description": "Reference schema for simulation Job."
},
{
"type": "null"
}
],
"description": "Simulation job created from optimization results"
},
"UpdateVariable": {
"items": {
"properties": {
"Variable": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"Slug": {
"type": "string",
"title": "Slug"
},
"Type": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes",
"description": "Varaible Tyeps."
},
"Group": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups",
"description": "Vraible groups."
}
},
"type": "object",
"required": [
"IId",
"Name",
"Slug",
"Type",
"Group"
],
"title": "VariableRef",
"description": "Variable reference."
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Value": {
"type": "number",
"title": "Value"
}
},
"type": "object",
"required": [
"Variable",
"Date",
"Value"
],
"title": "UpdateVariable",
"description": "Updated variables."
},
"type": "array",
"title": "Updatevariable",
"description": "Optimized variable values (the solution)"
},
"AttributionAssociation": {
"items": {
"properties": {
"Attribution": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
}
},
"type": "object",
"required": [
"Attribution"
],
"title": "OptimizationAttributionAssociation",
"description": "Reference schema for optimization attribution association."
},
"type": "array",
"title": "Attributionassociation",
"description": "Attribution jobs linked to this optimization"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Date",
"Model",
"UpdateVariable",
"AttributionAssociation"
],
"title": "DetailedOptimization",
"description": "Detailed response schema for optimization jobs with results and constraints.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 456,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Q4 Budget Optimization",
"Note": "Optimizing marketing spend for Q4",
"Status": "completed",
"UIFilterAttributionAssociation": [],
"UpdateVariable": []
}
]
}
}
}
},
"404": {
"description": "Optimization job not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Optimization (/api/optimizations/update_optimization_projects__team_id___project_id__optimizations__optimization_id__patch)
Update metadata attributes of an optimization job.
Allows modification of mutable fields like Name and Note. Cannot modify
optimization parameters or results after job creation.
Response:
Updated optimization job object.
## PATCH /api/projects/{team_id}/{project_id}/optimizations/{optimization_id}
Update Optimization
Update metadata attributes of an optimization job.
Allows modification of mutable fields like Name and Note. Cannot modify
optimization parameters or results after job creation.
Response:
Updated optimization job object.
```json
{
"tags": [
"Optimizations"
],
"summary": "Update Optimization",
"description": "Update metadata attributes of an optimization job.\n\nAllows modification of mutable fields like Name and Note. Cannot modify\noptimization parameters or results after job creation.\n\nResponse:\n Updated optimization job object.",
"operationId": "update_optimization_projects__team_id___project_id__optimizations__optimization_id__patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "optimization_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide optimization IId",
"title": "Optimization Id"
},
"description": "Provide optimization IId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Description for the model/dataset"
}
},
"type": "object",
"title": "PatchOptimizationJobs",
"description": "Schema for updating optimization jobs.",
"examples": [
{
"Name": "Updated Optimization Job",
"Note": "Updated notes for this optimization"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"Model": {
"description": "Reference to the trained model used for optimization",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Params": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Params",
"description": "Full optimization configuration parameters"
},
"TargetResult": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Targetresult",
"description": "Final objective value achieved by optimization"
},
"BaselineTarget": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Baselinetarget",
"description": "Target goal value (for goal-seek optimizations)"
},
"BaselineTargetResult": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Baselinetargetresult",
"description": "Objective value at baseline (before optimization)"
},
"Improvement": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Improvement",
"description": "Percent improvement: (Target - Baseline) / Baseline"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Date",
"Model"
],
"title": "OptimizationJobs",
"description": "Response schema for optimization jobs listing and summary views.",
"examples": [
{
"BaselineTarget": 100000,
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"Improvement": 0.5,
"JobId": 456,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Q4 Budget Optimization",
"Note": "Optimizing marketing spend for Q4",
"Status": "completed",
"TargetResult": 150000
}
]
}
}
}
},
"404": {
"description": "Optimization job not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Optimization (/api/optimizations/delete_optimization_projects__team_id___project_id__optimizations__optimization_id__delete)
Delete an optimization job and its associated data.
Marks the optimization job for deletion and triggers background cleanup.
The deletion is asynchronous - the job is immediately hidden from
listings but data cleanup happens in the background.
Path Parameters:
- optimization_id: The IId of the optimization job to delete
Notes:
- Deletion is permanent and cannot be undone
- Associated simulation and attribution jobs are also deleted
- Results data is purged from storage
## DELETE /api/projects/{team_id}/{project_id}/optimizations/{optimization_id}
Delete Optimization
Delete an optimization job and its associated data.
Marks the optimization job for deletion and triggers background cleanup.
The deletion is asynchronous - the job is immediately hidden from
listings but data cleanup happens in the background.
Path Parameters:
- optimization_id: The IId of the optimization job to delete
Notes:
- Deletion is permanent and cannot be undone
- Associated simulation and attribution jobs are also deleted
- Results data is purged from storage
```json
{
"tags": [
"Optimizations"
],
"summary": "Delete Optimization",
"description": "Delete an optimization job and its associated data.\n\nMarks the optimization job for deletion and triggers background cleanup.\nThe deletion is asynchronous - the job is immediately hidden from\nlistings but data cleanup happens in the background.\n\nPath Parameters:\n - optimization_id: The IId of the optimization job to delete\n\nNotes:\n - Deletion is permanent and cannot be undone\n - Associated simulation and attribution jobs are also deleted\n - Results data is purged from storage",
"operationId": "delete_optimization_projects__team_id___project_id__optimizations__optimization_id__delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "optimization_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide optimization IId",
"title": "Optimization Id"
},
"description": "Provide optimization IId"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Optimization job not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Optimization Dates Min Max (/api/optimizations/get_optimization_dates_min_max_projects__team_id___project_id__optimizations__optimization_id__dates_min_max_get)
Get min and max dates from optimization result data.
## GET /api/projects/{team_id}/{project_id}/optimizations/{optimization_id}/dates_min_max
Get Optimization Dates Min Max
Get min and max dates from optimization result data.
```json
{
"tags": [
"Optimizations"
],
"summary": "Get Optimization Dates Min Max",
"description": "Get min and max dates from optimization result data.",
"operationId": "get_optimization_dates_min_max_projects__team_id___project_id__optimizations__optimization_id__dates_min_max_get",
"parameters": [
{
"name": "optimization_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide optimization IId",
"title": "Optimization Id"
},
"description": "Provide optimization IId"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"min": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Min"
},
"max": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Max"
}
},
"type": "object",
"required": [
"min",
"max"
],
"title": "DateRange",
"description": "Min and max dates for a resource collection."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Optimzation (/api/optimizations/download_optimzation_projects__team_id___project_id__optimizations__optimization_id__data_get)
Download optimal variable allocations as a CSV file.
Returns the optimized values for each variable across the time range.
Use these values in predictions or simulations to see the impact of
the optimal allocation.
Prerequisites:
Job Status must be COMPLETED. Poll GET /optimizations/{optimization_id}
until Status is COMPLETED before calling this endpoint.
Path Parameters:
- optimization_id: The IId of the optimization job
Query Parameters:
- result_filters: JSON filter expressions to subset results
Response:
CSV file stream with columns:
- Date: Time period
- Variable: Variable slug that was optimized
- Value: Optimal value for that variable/date
Related:
- POST /optimizations/{optimization_id}/simulate: Run simulation
- GET /optimizations/{optimization_id}/predict_simulate_input
## GET /api/projects/{team_id}/{project_id}/optimizations/{optimization_id}/data
Download Optimzation
Download optimal variable allocations as a CSV file.
Returns the optimized values for each variable across the time range.
Use these values in predictions or simulations to see the impact of
the optimal allocation.
Prerequisites:
Job Status must be COMPLETED. Poll GET /optimizations/{optimization_id}
until Status is COMPLETED before calling this endpoint.
Path Parameters:
- optimization_id: The IId of the optimization job
Query Parameters:
- result_filters: JSON filter expressions to subset results
Response:
CSV file stream with columns:
- Date: Time period
- Variable: Variable slug that was optimized
- Value: Optimal value for that variable/date
Related:
- POST /optimizations/{optimization_id}/simulate: Run simulation
- GET /optimizations/{optimization_id}/predict_simulate_input
```json
{
"tags": [
"Optimizations"
],
"summary": "Download Optimzation",
"description": "Download optimal variable allocations as a CSV file.\n\nReturns the optimized values for each variable across the time range.\nUse these values in predictions or simulations to see the impact of\nthe optimal allocation.\n\nPrerequisites:\n Job Status must be COMPLETED. Poll GET /optimizations/{optimization_id}\n until Status is COMPLETED before calling this endpoint.\n\nPath Parameters:\n - optimization_id: The IId of the optimization job\n\nQuery Parameters:\n - result_filters: JSON filter expressions to subset results\n\nResponse:\n CSV file stream with columns:\n - Date: Time period\n - Variable: Variable slug that was optimized\n - Value: Optimal value for that variable/date\n\nRelated:\n - POST /optimizations/{optimization_id}/simulate: Run simulation\n - GET /optimizations/{optimization_id}/predict_simulate_input",
"operationId": "download_optimzation_projects__team_id___project_id__optimizations__optimization_id__data_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "optimization_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide optimization IId",
"title": "Optimization Id"
},
"description": "Provide optimization IId"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "result_filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n Filter optimization result data rows.\n\n Examples:\n - By country: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - Multiple: result_filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"media_spend\"]]}'\n - Combined: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n ",
"title": "Result Filters"
},
"description": "\n Filter optimization result data rows.\n\n Examples:\n - By country: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n - Multiple: result_filters='{\"Country\": [[\"in\", \"[\\\"USA\\\", \\\"GBR\\\"]\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"media_spend\"]]}'\n - Combined: result_filters='{\"Country\": [[\"=\", \"USA\"]]}'\n "
},
{
"name": "output_format",
"in": "query",
"required": false,
"schema": {
"enum": [
"csv",
"parquet"
],
"type": "string",
"default": "csv",
"title": "Output Format"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"description": "Optimization job not in COMPLETED status - poll status first",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Optimization job not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Optimization Query (/api/optimizations/download_optimization_query_projects__team_id___project_id__optimizations__optimization_id__data_query_post)
Download optimal variable allocations — POST variant for large filter payloads.
## POST /api/projects/{team_id}/{project_id}/optimizations/{optimization_id}/data_query
Download Optimization Query
Download optimal variable allocations — POST variant for large filter payloads.
```json
{
"tags": [
"Optimizations"
],
"summary": "Download Optimization Query",
"description": "Download optimal variable allocations — POST variant for large filter payloads.",
"operationId": "download_optimization_query_projects__team_id___project_id__optimizations__optimization_id__data_query_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "optimization_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide optimization IId",
"title": "Optimization Id"
},
"description": "Provide optimization IId"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"result_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Result Filters"
},
"output_format": {
"type": "string",
"enum": [
"csv",
"parquet"
],
"title": "Output Format",
"default": "csv"
}
},
"type": "object",
"title": "ResultFiltersBody",
"description": "Request body for _query POST endpoints that filter result data rows."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"description": "Optimization job not in COMPLETED status - poll status first",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Optimization job not found with the specified ID",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Simulate With Optimization Result (/api/optimizations/simulate_with_optimization_result_projects__team_id___project_id__optimizations__optimization_id__simulate_post)
Create a simulation using the optimal variable allocation.
Automatically creates and submits a simulation job using the optimized
variable values as the scenario. This allows you to visualize the full
forecast under the optimal allocation and compare against baseline.
Prerequisites:
Optimization job must be COMPLETED.
Path Parameters:
- optimization_id: The IId of the optimization job
Workflow:
1. Call this endpoint to create the simulation
2. Poll GET /simulations/{simulation_id} until COMPLETED
3. Download results via GET /simulations/{simulation_id}/data
Response:
Updated optimization job with SimulationJob reference populated.
Notes:
- Uses the same model and date range as the optimization
- Optimal values become the "Scenario" in the simulation
- Baseline values become "BaseScenario" for comparison
Related:
- GET /optimizations/{optimization_id}/data: Download optimal allocation
- GET /simulations/{simulation_id}/data: Download simulation results
## POST /api/projects/{team_id}/{project_id}/optimizations/{optimization_id}/simulate
Simulate With Optimization Result
Create a simulation using the optimal variable allocation.
Automatically creates and submits a simulation job using the optimized
variable values as the scenario. This allows you to visualize the full
forecast under the optimal allocation and compare against baseline.
Prerequisites:
Optimization job must be COMPLETED.
Path Parameters:
- optimization_id: The IId of the optimization job
Workflow:
1. Call this endpoint to create the simulation
2. Poll GET /simulations/{simulation_id} until COMPLETED
3. Download results via GET /simulations/{simulation_id}/data
Response:
Updated optimization job with SimulationJob reference populated.
Notes:
- Uses the same model and date range as the optimization
- Optimal values become the "Scenario" in the simulation
- Baseline values become "BaseScenario" for comparison
Related:
- GET /optimizations/{optimization_id}/data: Download optimal allocation
- GET /simulations/{simulation_id}/data: Download simulation results
```json
{
"tags": [
"Optimizations"
],
"summary": "Simulate With Optimization Result",
"description": "Create a simulation using the optimal variable allocation.\n\nAutomatically creates and submits a simulation job using the optimized\nvariable values as the scenario. This allows you to visualize the full\nforecast under the optimal allocation and compare against baseline.\n\nPrerequisites:\n Optimization job must be COMPLETED.\n\nPath Parameters:\n - optimization_id: The IId of the optimization job\n\nWorkflow:\n 1. Call this endpoint to create the simulation\n 2. Poll GET /simulations/{simulation_id} until COMPLETED\n 3. Download results via GET /simulations/{simulation_id}/data\n\nResponse:\n Updated optimization job with SimulationJob reference populated.\n\nNotes:\n - Uses the same model and date range as the optimization\n - Optimal values become the \"Scenario\" in the simulation\n - Baseline values become \"BaseScenario\" for comparison\n\nRelated:\n - GET /optimizations/{optimization_id}/data: Download optimal allocation\n - GET /simulations/{simulation_id}/data: Download simulation results",
"operationId": "simulate_with_optimization_result_projects__team_id___project_id__optimizations__optimization_id__simulate_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "optimization_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide optimization IId",
"title": "Optimization Id"
},
"description": "Provide optimization IId"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"Task": {
"anyOf": [
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"Topic": {
"type": "string",
"enum": [
"ATTRIBUTIONSET",
"ATTRIBUTIONJOB",
"SIMULATIONJOB",
"PREDICTIONJOB",
"TRAINJOB",
"DATASET",
"DATAUPLOAD",
"GRAPHCONSTRUCT",
"GENERAL",
"OPTIMIZATIONJOB",
"RESPOSNSECURVEJOB",
"PRIORPOSTERIORJOB",
"EXCELJOB",
"GRAPHBASIC",
"FEATUREIMPORTANCE",
"GRAPHSYNERGY"
],
"title": "TaskTopics",
"description": "Task topics."
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"Id",
"Config",
"Topic",
"Status"
],
"title": "Task",
"description": "Reference task."
},
{
"type": "null"
}
]
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"Model": {
"description": "Reference to the trained model used for optimization",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Params": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Params",
"description": "Full optimization configuration parameters"
},
"TargetResult": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Targetresult",
"description": "Final objective value achieved by optimization"
},
"BaselineTarget": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Baselinetarget",
"description": "Target goal value (for goal-seek optimizations)"
},
"BaselineTargetResult": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Baselinetargetresult",
"description": "Objective value at baseline (before optimization)"
},
"Improvement": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Improvement",
"description": "Percentage improvement over baseline"
},
"Loss": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Loss",
"description": "Final objective function loss value"
},
"ConstraintLoss": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Constraintloss",
"description": "Penalty from constraint violations"
},
"ConstraintViolations": {
"anyOf": [
{
"items": {
"properties": {
"Id": {
"type": "integer",
"title": "Id"
},
"Value": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Value"
},
"Violation": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Violation"
},
"Constraint": {
"title": "Constraint"
}
},
"type": "object",
"required": [
"Id",
"Constraint"
],
"title": "ConstraintViolations",
"description": "Referenche schema for ConstraintViolations."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Constraintviolations",
"description": "List of violated constraints with details"
},
"ConstraintViolation": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Constraintviolation",
"description": "Total constraint violation magnitude"
},
"AdditionalConfig": {
"anyOf": [
{},
{
"type": "null"
}
],
"title": "Additionalconfig",
"description": "Additional optimization configuration"
},
"Seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Seed used for reproducible runs"
},
"SimulationJob": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"IsFromOptimization": {
"type": "boolean",
"title": "Isfromoptimization",
"description": "Whether this simulation was submitted by an optimization job.",
"readOnly": true
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"IsFromOptimization"
],
"title": "SimulationJobsRef",
"description": "Reference schema for simulation Job."
},
{
"type": "null"
}
],
"description": "Simulation job created from optimization results"
},
"UpdateVariable": {
"items": {
"properties": {
"Variable": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"Slug": {
"type": "string",
"title": "Slug"
},
"Type": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model"
],
"title": "VariableTypes",
"description": "Varaible Tyeps."
},
"Group": {
"type": "string",
"enum": [
"Brand",
"CompetitorBrand",
"Distribution",
"CompetitorDistribution",
"Events",
"Macro",
"Media",
"CustomerExperience",
"CompetitorMedia",
"Sales",
"CompetitorPrice",
"Visits",
"Weather",
"Extra",
"Model",
"Price",
"Profit",
"Cost",
"Data",
"KPI",
"Season",
"Trend",
"Connect",
"Experimental",
"Advanced",
"Math",
"Customer_experience",
"Competitor_price",
"Competitor_media",
"Competitor_brand",
"Competitor_distribution",
"Event",
"Holiday",
"Base",
"Revenue",
"Dates"
],
"title": "VariableGroups",
"description": "Vraible groups."
}
},
"type": "object",
"required": [
"IId",
"Name",
"Slug",
"Type",
"Group"
],
"title": "VariableRef",
"description": "Variable reference."
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Value": {
"type": "number",
"title": "Value"
}
},
"type": "object",
"required": [
"Variable",
"Date",
"Value"
],
"title": "UpdateVariable",
"description": "Updated variables."
},
"type": "array",
"title": "Updatevariable",
"description": "Optimized variable values (the solution)"
},
"AttributionAssociation": {
"items": {
"properties": {
"Attribution": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date"
},
"Status": {
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState",
"description": "Drun job states."
},
"DataSet": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef",
"description": "Reference schema for DataSet."
},
"Model": {
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"DataSet",
"Model"
],
"title": "AttributionRef",
"description": "Schema for Attribution jobs."
}
},
"type": "object",
"required": [
"Attribution"
],
"title": "OptimizationAttributionAssociation",
"description": "Reference schema for optimization attribution association."
},
"type": "array",
"title": "Attributionassociation",
"description": "Attribution jobs linked to this optimization"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Date",
"Model",
"UpdateVariable",
"AttributionAssociation"
],
"title": "DetailedOptimization",
"description": "Detailed response schema for optimization jobs with results and constraints.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 456,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Q4 Budget Optimization",
"Note": "Optimizing marketing spend for Q4",
"Status": "completed",
"UIFilterAttributionAssociation": [],
"UpdateVariable": []
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Response Curves (/api/response-curves/list_response_curves_projects__team_id___project_id__response_curve_get)
List response curve jobs.
This endpoint retrieves a paginated list of response curve jobs based on
the provided filters within a specified project.
## GET /api/projects/{team_id}/{project_id}/response_curve
List Response Curves
List response curve jobs.
This endpoint retrieves a paginated list of response curve jobs based on
the provided filters within a specified project.
```json
{
"tags": [
"Response Curves"
],
"summary": "List Response Curves",
"description": "List response curve jobs.\n\nThis endpoint retrieves a paginated list of response curve jobs based on\nthe provided filters within a specified project.",
"operationId": "list_response_curves_projects__team_id___project_id__response_curve_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"US_Model\"]]}'\n - Recent jobs: filters='{\"Date\": [[\">=\", \"2024-10-01\"]]}'\n - Sort by date: filters='{\"Date\": [[\"orderby\", \"desc\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"US_Model\"]]}'\n - Recent jobs: filters='{\"Date\": [[\">=\", \"2024-10-01\"]]}'\n - Sort by date: filters='{\"Date\": [[\"orderby\", \"desc\"]]}'\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Model": {
"description": "Reference to the trained model used for analysis",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Model",
"Date"
],
"title": "ResponseCurve",
"description": "Response schema for response curve analysis jobs.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 789,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Response Curve Analysis",
"Note": "Analyzing marketing spend response",
"Status": "completed"
}
]
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[ResponseCurve]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Submit Response Curve (/api/response-curves/submit_response_curve_projects__team_id___project_id__response_curve_post)
Submit a response curve job.
This endpoint submits a response curve job based on the provided request data,
project, and session.
## POST /api/projects/{team_id}/{project_id}/response_curve
Submit Response Curve
Submit a response curve job.
This endpoint submits a response curve job based on the provided request data,
project, and session.
```json
{
"tags": [
"Response Curves"
],
"summary": "Submit Response Curve",
"description": "Submit a response curve job.\n\nThis endpoint submits a response curve job based on the provided request data,\nproject, and session.",
"operationId": "submit_response_curve_projects__team_id___project_id__response_curve_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
},
"curve_inputs": {
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable",
"description": "Variable slug."
},
"start_val": {
"type": "number",
"title": "Start Val"
},
"end_val": {
"type": "number",
"title": "End Val"
},
"steps": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Steps",
"default": 10
}
},
"type": "object",
"required": [
"variable",
"start_val",
"end_val"
],
"title": "ResponseCurveInput",
"description": "Settings for values the response curve shoule be calcualted for."
},
"type": "array",
"title": "Curve Inputs"
},
"model_id": {
"type": "integer",
"title": "Model Id",
"description": "The id of the model that should be used to do the response job with."
},
"start_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Start Date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "End Date"
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
},
"samples": {
"type": "integer",
"title": "The samples",
"description": "Hom many subsamples to draw from the posterior distribution. The higher number of samples the better the uncertainty estimation becomes but it also takes longer to run.",
"default": 10
},
"quantiles": {
"anyOf": [
{
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Quantiles",
"default": [
20,
40,
50,
60,
80
]
},
"seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Optional integer seed for reproducible runs. If omitted, the server generates a random seed."
},
"validate_limits": {
"type": "boolean",
"title": "Validate Limits",
"description": "Validate values against per-variable min/max limits.",
"default": false
}
},
"type": "object",
"required": [
"model_id"
],
"title": "ResponseCurvePost",
"description": "Response curve submit.",
"examples": [
{
"curve_inputs": [
{
"end_val": 100000,
"start_val": 0,
"steps": 20,
"variable": "tv_spend"
},
{
"end_val": 50000,
"start_val": 0,
"steps": 15,
"variable": "digital_spend"
}
],
"dataset_id": "active",
"end_date": "2024-12-31T00:00:00Z",
"model_id": 1,
"name": "TV Spend Response Curve",
"note": "Analyze diminishing returns on TV advertising",
"priority": 30,
"quantiles": [
20,
40,
50,
60,
80
],
"samples": 10,
"start_date": "2024-01-01T00:00:00Z"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Model": {
"description": "Reference to the trained model used for analysis",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Model",
"Date"
],
"title": "ResponseCurve",
"description": "Response schema for response curve analysis jobs.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 789,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Response Curve Analysis",
"Note": "Analyzing marketing spend response",
"Status": "completed"
}
]
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Bulk Delete Response Curves (/api/response-curves/bulk_delete_response_curves_projects__team_id___project_id__response_curve_delete)
Bulk delete response curve jobs matching the given filters.
Marks all matching jobs for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
## DELETE /api/projects/{team_id}/{project_id}/response_curve
Bulk Delete Response Curves
Bulk delete response curve jobs matching the given filters.
Marks all matching jobs for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
```json
{
"tags": [
"Response Curves"
],
"summary": "Bulk Delete Response Curves",
"description": "Bulk delete response curve jobs matching the given filters.\n\nMarks all matching jobs for deletion and publishes delete messages to\nRabbitMQ concurrently in the background via a single DB round-trip each.",
"operationId": "bulk_delete_response_curves_projects__team_id___project_id__response_curve_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"US_Model\"]]}'\n - By date: filters='{\"Date\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"US_Model\"]]}'\n - By date: filters='{\"Date\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n "
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Response Curve (/api/response-curves/get_response_curve_projects__team_id___project_id__response_curve__curve_id__get)
Get detailed response curve job.
This endpoint retrieves detailed information about a specific response curve job.
## GET /api/projects/{team_id}/{project_id}/response_curve/{curve_id}
Get Response Curve
Get detailed response curve job.
This endpoint retrieves detailed information about a specific response curve job.
```json
{
"tags": [
"Response Curves"
],
"summary": "Get Response Curve",
"description": "Get detailed response curve job.\n\nThis endpoint retrieves detailed information about a specific response curve job.",
"operationId": "get_response_curve_projects__team_id___project_id__response_curve__curve_id__get",
"parameters": [
{
"name": "curve_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Response curve job IId.",
"title": "Curve Id"
},
"description": "Response curve job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"Task": {
"anyOf": [
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"Topic": {
"type": "string",
"enum": [
"ATTRIBUTIONSET",
"ATTRIBUTIONJOB",
"SIMULATIONJOB",
"PREDICTIONJOB",
"TRAINJOB",
"DATASET",
"DATAUPLOAD",
"GRAPHCONSTRUCT",
"GENERAL",
"OPTIMIZATIONJOB",
"RESPOSNSECURVEJOB",
"PRIORPOSTERIORJOB",
"EXCELJOB",
"GRAPHBASIC",
"FEATUREIMPORTANCE",
"GRAPHSYNERGY"
],
"title": "TaskTopics",
"description": "Task topics."
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"Id",
"Config",
"Topic",
"Status"
],
"title": "Task",
"description": "Reference task."
},
{
"type": "null"
}
]
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Model": {
"description": "Reference to the trained model used for analysis",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"InputPoints": {
"anyOf": [
{
"items": {
"properties": {
"Variable": {
"properties": {
"Slug": {
"type": "string",
"title": "Slug"
}
},
"type": "object",
"required": [
"Slug"
],
"title": "_Variable"
},
"StartVal": {
"type": "number",
"title": "Startval"
},
"EndVal": {
"type": "number",
"title": "Endval"
},
"Steps": {
"type": "integer",
"title": "Steps"
}
},
"type": "object",
"required": [
"Variable",
"StartVal",
"EndVal",
"Steps"
],
"title": "_InputPoint"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Inputpoints",
"description": "Input variable ranges for response curve generation"
},
"Seed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Seed",
"description": "Seed used for reproducible runs"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Model",
"Date"
],
"title": "ResponseCurveDetailed",
"description": "Detailed response schema for response curve analysis with input points.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 789,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Response Curve Analysis",
"Note": "Analyzing marketing spend response",
"Status": "completed"
}
]
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Response Curve Job (/api/response-curves/update_response_curve_job_projects__team_id___project_id__response_curve__curve_id__patch)
Update a response curve job.
This endpoint updates the attributes of an existing response curve job based on
the provided update data.
## PATCH /api/projects/{team_id}/{project_id}/response_curve/{curve_id}
Update Response Curve Job
Update a response curve job.
This endpoint updates the attributes of an existing response curve job based on
the provided update data.
```json
{
"tags": [
"Response Curves"
],
"summary": "Update Response Curve Job",
"description": "Update a response curve job.\n\nThis endpoint updates the attributes of an existing response curve job based on\nthe provided update data.",
"operationId": "update_response_curve_job_projects__team_id___project_id__response_curve__curve_id__patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "curve_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Response curve job IId.",
"title": "Curve Id"
},
"description": "Response curve job IId."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Description for the model/dataset"
}
},
"type": "object",
"title": "PatchResponseCurveJobs",
"description": "Schema for updating response curve job.",
"examples": [
{
"Name": "Updated Response Curve",
"Note": "Updated notes for this response curve job"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Model": {
"description": "Reference to the trained model used for analysis",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Model",
"Date"
],
"title": "ResponseCurve",
"description": "Response schema for response curve analysis jobs.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 789,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Response Curve Analysis",
"Note": "Analyzing marketing spend response",
"Status": "completed"
}
]
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Response Curve (/api/response-curves/delete_response_curve_projects__team_id___project_id__response_curve__curve_id__delete)
Delete a response curve job.
This endpoint deletes a specified response curve job.
## DELETE /api/projects/{team_id}/{project_id}/response_curve/{curve_id}
Delete Response Curve
Delete a response curve job.
This endpoint deletes a specified response curve job.
```json
{
"tags": [
"Response Curves"
],
"summary": "Delete Response Curve",
"description": "Delete a response curve job.\n\nThis endpoint deletes a specified response curve job.",
"operationId": "delete_response_curve_projects__team_id___project_id__response_curve__curve_id__delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "curve_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Response curve job IId.",
"title": "Curve Id"
},
"description": "Response curve job IId."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Response Curve Dates Min Max (/api/response-curves/get_response_curve_dates_min_max_projects__team_id___project_id__response_curve__curve_id__dates_min_max_get)
Get min and max dates from temporal curve result data.
## GET /api/projects/{team_id}/{project_id}/response_curve/{curve_id}/dates_min_max
Get Response Curve Dates Min Max
Get min and max dates from temporal curve result data.
```json
{
"tags": [
"Response Curves"
],
"summary": "Get Response Curve Dates Min Max",
"description": "Get min and max dates from temporal curve result data.",
"operationId": "get_response_curve_dates_min_max_projects__team_id___project_id__response_curve__curve_id__dates_min_max_get",
"parameters": [
{
"name": "curve_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Response curve job IId.",
"title": "Curve Id"
},
"description": "Response curve job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"min": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Min"
},
"max": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Max"
}
},
"type": "object",
"required": [
"min",
"max"
],
"title": "DateRange",
"description": "Min and max dates for a resource collection."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Response Curve (/api/response-curves/download_response_curve_projects__team_id___project_id__response_curve__curve_id__data_get)
Get response curve result as CSV file.
This endpoint retrieves the results of a specified response curve job and returns
the data as a CSV file.
## GET /api/projects/{team_id}/{project_id}/response_curve/{curve_id}/data
Download Response Curve
Get response curve result as CSV file.
This endpoint retrieves the results of a specified response curve job and returns
the data as a CSV file.
```json
{
"tags": [
"Response Curves"
],
"summary": "Download Response Curve",
"description": "Get response curve result as CSV file.\n\nThis endpoint retrieves the results of a specified response curve job and returns\nthe data as a CSV file.",
"operationId": "download_response_curve_projects__team_id___project_id__response_curve__curve_id__data_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "curve_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Response curve job IId.",
"title": "Curve Id"
},
"description": "Response curve job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "result_filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n Filter response curve result data rows.\n\n Examples:\n - By quantile: result_filters='{\"Quantile\": [[\"=\", \"50\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"media\"]]}'\n ",
"title": "Result Filters"
},
"description": "\n Filter response curve result data rows.\n\n Examples:\n - By quantile: result_filters='{\"Quantile\": [[\"=\", \"50\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"media\"]]}'\n "
},
{
"name": "output_format",
"in": "query",
"required": false,
"schema": {
"enum": [
"csv",
"parquet"
],
"type": "string",
"default": "csv",
"title": "Output Format"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Response Curve Query (/api/response-curves/download_response_curve_query_projects__team_id___project_id__response_curve__curve_id__data_query_post)
Get response curve results — POST variant for large filter payloads.
## POST /api/projects/{team_id}/{project_id}/response_curve/{curve_id}/data_query
Download Response Curve Query
Get response curve results — POST variant for large filter payloads.
```json
{
"tags": [
"Response Curves"
],
"summary": "Download Response Curve Query",
"description": "Get response curve results — POST variant for large filter payloads.",
"operationId": "download_response_curve_query_projects__team_id___project_id__response_curve__curve_id__data_query_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "curve_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Response curve job IId.",
"title": "Curve Id"
},
"description": "Response curve job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"result_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Result Filters"
},
"output_format": {
"type": "string",
"enum": [
"csv",
"parquet"
],
"title": "Output Format",
"default": "csv"
}
},
"type": "object",
"title": "ResultFiltersBody",
"description": "Request body for _query POST endpoints that filter result data rows."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Temporal Csv Output (/api/response-curves/get_temporal_csv_output_projects__team_id___project_id__response_curve__curve_id__temporal_get)
Get response curve temporal result as CSV file.
This endpoint retrieves the temporal results of a specified response curve job and
returns the data as a CSV file.
## GET /api/projects/{team_id}/{project_id}/response_curve/{curve_id}/temporal
Get Temporal Csv Output
Get response curve temporal result as CSV file.
This endpoint retrieves the temporal results of a specified response curve job and
returns the data as a CSV file.
```json
{
"tags": [
"Response Curves"
],
"summary": "Get Temporal Csv Output",
"description": "Get response curve temporal result as CSV file.\n\nThis endpoint retrieves the temporal results of a specified response curve job and\nreturns the data as a CSV file.",
"operationId": "get_temporal_csv_output_projects__team_id___project_id__response_curve__curve_id__temporal_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "curve_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Response curve job IId.",
"title": "Curve Id"
},
"description": "Response curve job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "result_filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n Filter response curve data rows.\n\n Examples:\n - By variable: result_filters='{\"Variable\": [[\"=\", \"media_tv_spend\"]]}'\n - Multiple: result_filters='{\"Variable\": [[\"in\", \"[\\\"media_tv\\\"]\"]]}'\n ",
"title": "Result Filters"
},
"description": "\n Filter response curve data rows.\n\n Examples:\n - By variable: result_filters='{\"Variable\": [[\"=\", \"media_tv_spend\"]]}'\n - Multiple: result_filters='{\"Variable\": [[\"in\", \"[\\\"media_tv\\\"]\"]]}'\n "
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Temporal Csv Output Query (/api/response-curves/get_temporal_csv_output_query_projects__team_id___project_id__response_curve__curve_id__temporal_query_post)
Get response curve temporal results — POST variant for large filter payloads.
## POST /api/projects/{team_id}/{project_id}/response_curve/{curve_id}/temporal_query
Get Temporal Csv Output Query
Get response curve temporal results — POST variant for large filter payloads.
```json
{
"tags": [
"Response Curves"
],
"summary": "Get Temporal Csv Output Query",
"description": "Get response curve temporal results — POST variant for large filter payloads.",
"operationId": "get_temporal_csv_output_query_projects__team_id___project_id__response_curve__curve_id__temporal_query_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "curve_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Response curve job IId.",
"title": "Curve Id"
},
"description": "Response curve job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"result_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Result Filters"
},
"output_format": {
"type": "string",
"enum": [
"csv",
"parquet"
],
"title": "Output Format",
"default": "csv"
}
},
"type": "object",
"title": "ResultFiltersBody",
"description": "Request body for _query POST endpoints that filter result data rows."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Prior Vs Posterior (/api/prior-posterior/list_prior_vs_posterior_projects__team_id___project_id__prior_posterior_get)
List prior vs posterior jobs.
This endpoint retrieves a paginated list of prior vs posterior jobs based on
the provided filters within a specified project.
## GET /api/projects/{team_id}/{project_id}/prior_posterior
List Prior Vs Posterior
List prior vs posterior jobs.
This endpoint retrieves a paginated list of prior vs posterior jobs based on
the provided filters within a specified project.
```json
{
"tags": [
"Prior Posterior"
],
"summary": "List Prior Vs Posterior",
"description": "List prior vs posterior jobs.\n\nThis endpoint retrieves a paginated list of prior vs posterior jobs based on\nthe provided filters within a specified project.",
"operationId": "list_prior_vs_posterior_projects__team_id___project_id__prior_posterior_get",
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"US_Model\"]]}'\n - Recent jobs: filters='{\"Date\": [[\">=\", \"2024-10-01\"]]}'\n - Sort by date: filters='{\"Date\": [[\"orderby\", \"desc\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"US_Model\"]]}'\n - Recent jobs: filters='{\"Date\": [[\">=\", \"2024-10-01\"]]}'\n - Sort by date: filters='{\"Date\": [[\"orderby\", \"desc\"]]}'\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Model": {
"description": "Reference to the trained model used for analysis",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"ReferencePointFallback": {
"description": "How to handle missing reference points: 'zero' or 'mean'",
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback"
},
"FitModel": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
},
{
"type": "null"
}
],
"description": "Reference model for fit comparison (if analyzing model fit)"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Model",
"Date",
"ReferencePointFallback"
],
"title": "PriorPosterior",
"description": "Response schema for prior vs posterior distribution analysis jobs.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 101,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Prior Posterior Analysis",
"Note": "Comparing prior and posterior distributions",
"ReferencePointFallback": "Zero",
"Status": "completed"
}
]
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[PriorPosterior]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Submit Prior Vs Posterior (/api/prior-posterior/submit_prior_vs_posterior_projects__team_id___project_id__prior_posterior_post)
Submit a prior posterior job.
This endpoint submits a prior posterior job based on the provided request data,
project, and session.
## POST /api/projects/{team_id}/{project_id}/prior_posterior
Submit Prior Vs Posterior
Submit a prior posterior job.
This endpoint submits a prior posterior job based on the provided request data,
project, and session.
```json
{
"tags": [
"Prior Posterior"
],
"summary": "Submit Prior Vs Posterior",
"description": "Submit a prior posterior job.\n\nThis endpoint submits a prior posterior job based on the provided request data,\nproject, and session.",
"operationId": "submit_prior_vs_posterior_projects__team_id___project_id__prior_posterior_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"samples": {
"type": "integer",
"title": "Samples",
"default": 100
},
"epochs": {
"type": "integer",
"title": "Epochs",
"default": 200
},
"sub_samples": {
"type": "integer",
"title": "Sub Samples",
"default": 3
},
"lr": {
"type": "number",
"title": "Lr",
"default": 0.01
},
"grad_clip": {
"type": "number",
"title": "The grad clip",
"description": "The value the gradient will be clipped during training to prevent exploding gradients.",
"default": 3
},
"baseline": {
"anyOf": [
{
"items": {
"properties": {
"variable": {
"type": "string",
"title": "Variable",
"description": "Variable slug."
},
"baseline": {
"type": "number",
"title": "Baseline",
"description": "Set baseline."
}
},
"type": "object",
"required": [
"variable",
"baseline"
],
"title": "ReferencePointBaseline",
"description": "Attribution job baseline."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Baseline"
},
"referece_point_fallback": {
"anyOf": [
{
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback",
"description": "Attribution's reference point fallback."
},
{
"type": "null"
}
],
"description": "Reference point fallback.",
"default": "Zero"
},
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 30
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
},
"model_id": {
"type": "integer",
"title": "Model Id",
"description": "The id of the model that should be used to do the response job with."
},
"quantiles": {
"anyOf": [
{
"items": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Quantiles",
"default": [
1,
5,
10,
15,
20,
25,
30,
35,
40,
45,
50,
55,
60,
65,
70,
75,
80,
85,
90,
95,
99
]
},
"fit_priorposterior": {
"type": "boolean",
"title": "Fit Priorposterior",
"description": "Whether to set prior posterior job as fit or not.",
"default": false
}
},
"type": "object",
"required": [
"model_id"
],
"title": "PriorPosteriorPost",
"description": "Prior posterior submit.",
"examples": [
{
"baseline": [
{
"baseline": 1000,
"variable": "base_sales"
}
],
"dataset_id": "active",
"epochs": 200,
"fit_priorposterior": true,
"grad_clip": 3,
"lr": 0.01,
"model_id": 1,
"name": "Prior Posterior Analysis",
"note": "Bayesian uncertainty analysis for model parameters",
"priority": 30,
"quantiles": [
1,
5,
10,
25,
50,
75,
90,
95,
99
],
"referece_point_fallback": "Zero",
"samples": 100,
"sub_samples": 3
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Model": {
"description": "Reference to the trained model used for analysis",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"ReferencePointFallback": {
"description": "How to handle missing reference points: 'zero' or 'mean'",
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback"
},
"FitModel": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
},
{
"type": "null"
}
],
"description": "Reference model for fit comparison (if analyzing model fit)"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Model",
"Date",
"ReferencePointFallback"
],
"title": "PriorPosterior",
"description": "Response schema for prior vs posterior distribution analysis jobs.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 101,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Prior Posterior Analysis",
"Note": "Comparing prior and posterior distributions",
"ReferencePointFallback": "Zero",
"Status": "completed"
}
]
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Bulk Delete Prior Posterior (/api/prior-posterior/bulk_delete_prior_posterior_projects__team_id___project_id__prior_posterior_delete)
Bulk delete prior vs posterior jobs matching the given filters.
Marks all matching jobs for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
## DELETE /api/projects/{team_id}/{project_id}/prior_posterior
Bulk Delete Prior Posterior
Bulk delete prior vs posterior jobs matching the given filters.
Marks all matching jobs for deletion and publishes delete messages to
RabbitMQ concurrently in the background via a single DB round-trip each.
```json
{
"tags": [
"Prior Posterior"
],
"summary": "Bulk Delete Prior Posterior",
"description": "Bulk delete prior vs posterior jobs matching the given filters.\n\nMarks all matching jobs for deletion and publishes delete messages to\nRabbitMQ concurrently in the background via a single DB round-trip each.",
"operationId": "bulk_delete_prior_posterior_projects__team_id___project_id__prior_posterior_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"US_Model\"]]}'\n - By date: filters='{\"Date\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /.\n\n Examples:\n - By status: filters='{\"Status\": [[\"=\", \"COMPLETED\"]]}'\n - By model: filters='{\"Model.Name\": [[\"contains\", \"US_Model\"]]}'\n - By date: filters='{\"Date\": [[\"<\", \"2024-01-01\"]]}'\n\n Operators: =, !=, >, >=, <, <=, contains, startswith, endswith,\n ilike, in, notin, is, isnot, orderby\n "
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Prior Vs Poterior (/api/prior-posterior/get_prior_vs_poterior_projects__team_id___project_id__prior_posterior__prior_posterior_id__get)
Get detailed prior vs posterior job.
This endpoint retrieves detailed information about
a specific prior vs posterior job.
## GET /api/projects/{team_id}/{project_id}/prior_posterior/{prior_posterior_id}
Get Prior Vs Poterior
Get detailed prior vs posterior job.
This endpoint retrieves detailed information about
a specific prior vs posterior job.
```json
{
"tags": [
"Prior Posterior"
],
"summary": "Get Prior Vs Poterior",
"description": "Get detailed prior vs posterior job.\n\nThis endpoint retrieves detailed information about\na specific prior vs posterior job.",
"operationId": "get_prior_vs_poterior_projects__team_id___project_id__prior_posterior__prior_posterior_id__get",
"parameters": [
{
"name": "prior_posterior_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Prior vs posterior job IId.",
"title": "Prior Posterior Id"
},
"description": "Prior vs posterior job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"Task": {
"anyOf": [
{
"properties": {
"Error": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Config": {
"additionalProperties": true,
"type": "object",
"title": "Config"
},
"Topic": {
"type": "string",
"enum": [
"ATTRIBUTIONSET",
"ATTRIBUTIONJOB",
"SIMULATIONJOB",
"PREDICTIONJOB",
"TRAINJOB",
"DATASET",
"DATAUPLOAD",
"GRAPHCONSTRUCT",
"GENERAL",
"OPTIMIZATIONJOB",
"RESPOSNSECURVEJOB",
"PRIORPOSTERIORJOB",
"EXCELJOB",
"GRAPHBASIC",
"FEATUREIMPORTANCE",
"GRAPHSYNERGY"
],
"title": "TaskTopics",
"description": "Task topics."
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
}
},
"type": "object",
"required": [
"Id",
"Config",
"Topic",
"Status"
],
"title": "Task",
"description": "Reference task."
},
{
"type": "null"
}
]
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Model": {
"description": "Reference to the trained model used for analysis",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"ReferencePointFallback": {
"description": "How to handle missing reference points: 'zero' or 'mean'",
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback"
},
"FitModel": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
},
{
"type": "null"
}
],
"description": "Reference model for fit comparison (if analyzing model fit)"
},
"Baseline": {
"anyOf": [
{
"items": {
"properties": {
"Variable": {
"properties": {
"Slug": {
"type": "string",
"title": "Slug"
}
},
"type": "object",
"required": [
"Slug"
],
"title": "_Variable"
},
"Baseline": {
"type": "number",
"title": "Baseline"
}
},
"type": "object",
"required": [
"Variable",
"Baseline"
],
"title": "AttrBaseline",
"description": "Schema for attribution baseline values."
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Baseline",
"description": "Baseline values for variables"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Model",
"Date",
"ReferencePointFallback"
],
"title": "DetailedPriorPosterior",
"description": "Detailed response schema for prior/posterior distribution analysis.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 101,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Prior Posterior Analysis",
"Note": "Comparing prior and posterior distributions",
"ReferencePointFallback": "Zero",
"Status": "completed"
}
]
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Prior Posterior Job (/api/prior-posterior/update_prior_posterior_job_projects__team_id___project_id__prior_posterior__prior_posterior_id__patch)
Update a prior posterior job.
This endpoint updates the attributes of an existing prior posterior job based on
the provided update data.
## PATCH /api/projects/{team_id}/{project_id}/prior_posterior/{prior_posterior_id}
Update Prior Posterior Job
Update a prior posterior job.
This endpoint updates the attributes of an existing prior posterior job based on
the provided update data.
```json
{
"tags": [
"Prior Posterior"
],
"summary": "Update Prior Posterior Job",
"description": "Update a prior posterior job.\n\nThis endpoint updates the attributes of an existing prior posterior job based on\nthe provided update data.",
"operationId": "update_prior_posterior_job_projects__team_id___project_id__prior_posterior__prior_posterior_id__patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "prior_posterior_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Prior vs posterior job IId.",
"title": "Prior Posterior Id"
},
"description": "Prior vs posterior job IId."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Description for the model/dataset"
}
},
"type": "object",
"title": "PatchPriorPosteriorJobs",
"description": "Schema for updating response curve job.",
"examples": [
{
"Name": "Updated Prior Posterior Job",
"Note": "Updated notes for this prior posterior job"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier used in API paths (e.g., /predictions/{IId})"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"DataSet": {
"description": "Reference to the dataset used for this job",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"Name": {
"type": "string",
"title": "Name"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Status": {
"type": "string",
"enum": [
"submitted",
"running",
"failed",
"complete"
],
"title": "TaskState",
"description": "Comnav internal task states."
},
"Selected": {
"type": "boolean",
"title": "Selected"
}
},
"type": "object",
"required": [
"IId",
"Name",
"CreatedDate",
"Status",
"Selected"
],
"title": "DataSetRef"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "User-defined display name for the job"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "User-defined description or documentation"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Model": {
"description": "Reference to the trained model used for analysis",
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Job creation timestamp"
},
"ReferencePointFallback": {
"description": "How to handle missing reference points: 'zero' or 'mean'",
"type": "string",
"enum": [
"Min",
"Max",
"Zero"
],
"title": "ReferencePointFallback"
},
"FitModel": {
"anyOf": [
{
"properties": {
"IId": {
"type": "integer",
"title": "Iid"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Country": {
"type": "string",
"title": "Country"
},
"Region": {
"type": "string",
"title": "Region"
},
"Grouping": {
"type": "string",
"title": "Grouping"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
}
},
"type": "object",
"required": [
"IId",
"Country",
"Region",
"Grouping",
"CreatedDate"
],
"title": "ModelsRef",
"description": "Reference schema for models."
},
{
"type": "null"
}
],
"description": "Reference model for fit comparison (if analyzing model fit)"
}
},
"type": "object",
"required": [
"IId",
"DataSet",
"Status",
"Model",
"Date",
"ReferencePointFallback"
],
"title": "PriorPosterior",
"description": "Response schema for prior vs posterior distribution analysis jobs.",
"examples": [
{
"CreatorId": "user-123",
"DataSet": {
"CreatedDate": "2024-01-15T10:30:00Z",
"IId": 1,
"Name": "Marketing Dataset",
"Selected": true,
"Status": "complete"
},
"Date": "2024-01-15T10:30:00",
"IId": 1,
"JobId": 101,
"Model": {
"Country": "USA",
"CreatedDate": "2024-01-15T10:30:00",
"Grouping": "all",
"IId": 1,
"Name": "USA Model",
"Region": "all"
},
"Name": "Prior Posterior Analysis",
"Note": "Comparing prior and posterior distributions",
"ReferencePointFallback": "Zero",
"Status": "completed"
}
]
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Prior Posterior (/api/prior-posterior/delete_prior_posterior_projects__team_id___project_id__prior_posterior__prior_posterior_id__delete)
Delete a prior posterior job.
This endpoint deletes a specified prior posterior job.
## DELETE /api/projects/{team_id}/{project_id}/prior_posterior/{prior_posterior_id}
Delete Prior Posterior
Delete a prior posterior job.
This endpoint deletes a specified prior posterior job.
```json
{
"tags": [
"Prior Posterior"
],
"summary": "Delete Prior Posterior",
"description": "Delete a prior posterior job.\n\nThis endpoint deletes a specified prior posterior job.",
"operationId": "delete_prior_posterior_projects__team_id___project_id__prior_posterior__prior_posterior_id__delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "prior_posterior_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Prior vs posterior job IId.",
"title": "Prior Posterior Id"
},
"description": "Prior vs posterior job IId."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Prior Posterior (/api/prior-posterior/download_prior_posterior_projects__team_id___project_id__prior_posterior__prior_posterior_id__data_get)
Get prior posterior job result as CSV file.
This endpoint retrieves the results of a specified prior posterior job and returns
the data as a CSV file.
## GET /api/projects/{team_id}/{project_id}/prior_posterior/{prior_posterior_id}/data
Download Prior Posterior
Get prior posterior job result as CSV file.
This endpoint retrieves the results of a specified prior posterior job and returns
the data as a CSV file.
```json
{
"tags": [
"Prior Posterior"
],
"summary": "Download Prior Posterior",
"description": "Get prior posterior job result as CSV file.\n\nThis endpoint retrieves the results of a specified prior posterior job and returns\nthe data as a CSV file.",
"operationId": "download_prior_posterior_projects__team_id___project_id__prior_posterior__prior_posterior_id__data_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "prior_posterior_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Prior vs posterior job IId.",
"title": "Prior Posterior Id"
},
"description": "Prior vs posterior job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "result_filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n Filter prior/posterior result data rows.\n\n Examples:\n - By quantile: result_filters='{\"Quantile\": [[\"=\", \"50\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"media\"]]}'\n - By distribution type: result_filters='{\"Type\": [[\"=\", \"posterior\"]]}'\n ",
"title": "Result Filters"
},
"description": "\n Filter prior/posterior result data rows.\n\n Examples:\n - By quantile: result_filters='{\"Quantile\": [[\"=\", \"50\"]]}'\n - By variable: result_filters='{\"Variable\": [[\"contains\", \"media\"]]}'\n - By distribution type: result_filters='{\"Type\": [[\"=\", \"posterior\"]]}'\n "
},
{
"name": "output_format",
"in": "query",
"required": false,
"schema": {
"enum": [
"csv",
"parquet"
],
"type": "string",
"default": "csv",
"title": "Output Format"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Prior Posterior Query (/api/prior-posterior/download_prior_posterior_query_projects__team_id___project_id__prior_posterior__prior_posterior_id__data_query_post)
Get prior posterior results — POST variant for large filter payloads.
## POST /api/projects/{team_id}/{project_id}/prior_posterior/{prior_posterior_id}/data_query
Download Prior Posterior Query
Get prior posterior results — POST variant for large filter payloads.
```json
{
"tags": [
"Prior Posterior"
],
"summary": "Download Prior Posterior Query",
"description": "Get prior posterior results — POST variant for large filter payloads.",
"operationId": "download_prior_posterior_query_projects__team_id___project_id__prior_posterior__prior_posterior_id__data_query_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "prior_posterior_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Prior vs posterior job IId.",
"title": "Prior Posterior Id"
},
"description": "Prior vs posterior job IId."
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"result_filters": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Result Filters"
},
"output_format": {
"type": "string",
"enum": [
"csv",
"parquet"
],
"title": "Output Format",
"default": "csv"
}
},
"type": "object",
"title": "ResultFiltersBody",
"description": "Request body for _query POST endpoints that filter result data rows."
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Excel Export Tasks (/api/excel-jobs/list_excel_export_tasks_projects__team_id___project_id__excel_get)
List Excel jobs.
This endpoint retrieves a paginated list of Excel jobs based on the provided filters
within a specified project.
## GET /api/projects/{team_id}/{project_id}/excel
List Excel Export Tasks
List Excel jobs.
This endpoint retrieves a paginated list of Excel jobs based on the provided filters
within a specified project.
```json
{
"tags": [
"Excel Jobs"
],
"summary": "List Excel Export Tasks",
"description": "List Excel jobs.\n\nThis endpoint retrieves a paginated list of Excel jobs based on the provided filters\nwithin a specified project.",
"operationId": "list_excel_export_tasks_projects__team_id___project_id__excel_get",
"deprecated": true,
"parameters": [
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n Usage:\n filters='{\"Models.Name\" : [[ \"contains\", \"SomeName\"]]}'\n ",
"title": "Filters"
},
"description": "\n Usage:\n filters='{\"Models.Name\" : [[ \"contains\", \"SomeName\"]]}'\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier for the export job"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Export job creation timestamp"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Type": {
"type": "string",
"title": "Type",
"description": "Export type identifier"
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"Type"
],
"title": "ExcelJobs",
"description": "Response schema for Excel export jobs."
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[ExcelJobs]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Submit Excel Export Task (/api/excel-jobs/submit_excel_export_task_projects__team_id___project_id__excel_post)
Submit an Excel export task.
This endpoint submits an Excel job based on the provided request data, project,
and session.
## POST /api/projects/{team_id}/{project_id}/excel
Submit Excel Export Task
Submit an Excel export task.
This endpoint submits an Excel job based on the provided request data, project,
and session.
```json
{
"tags": [
"Excel Jobs"
],
"summary": "Submit Excel Export Task",
"description": "Submit an Excel export task.\n\nThis endpoint submits an Excel job based on the provided request data, project,\nand session.",
"operationId": "submit_excel_export_task_projects__team_id___project_id__excel_post",
"deprecated": true,
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"properties": {
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 90
},
"excel_type": {
"type": "string",
"const": "dataupload",
"title": "Excel Type",
"default": "dataupload"
},
"upload_id": {
"type": "integer",
"title": "Upload Id"
}
},
"type": "object",
"required": [
"upload_id"
],
"title": "ExcelPostDataUpload",
"description": "Post dataset excel job."
},
{
"properties": {
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 90
},
"excel_type": {
"type": "string",
"const": "dataset",
"title": "Excel Type",
"default": "dataset"
},
"dataset_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "DatasetType",
"description": "Dataset type."
},
{
"type": "null"
}
],
"title": "Dataset Id",
"description": "Id of dataset to use. Used 'active' or leave empty to use active dataset within project."
}
},
"type": "object",
"title": "ExcelPostDataset",
"description": "Post dataset excel job."
},
{
"properties": {
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 90
},
"excel_type": {
"type": "string",
"const": "attributionset",
"title": "Excel Type",
"default": "attributionset"
},
"attribution_set_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string",
"enum": [
"active"
],
"title": "AttributionSetType",
"description": "Attribution set type."
}
],
"title": "Attribution Set Id"
},
"quantile": {
"type": "integer",
"title": "Quantile",
"default": 50
}
},
"type": "object",
"required": [
"attribution_set_id"
],
"title": "ExcelPostAttributionSet",
"description": "Post attributionset excel job."
},
{
"properties": {
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 90
},
"excel_type": {
"type": "string",
"const": "attribution",
"title": "Excel Type",
"default": "attribution"
},
"attribution_id": {
"type": "integer",
"title": "Attribution Id"
},
"quantile": {
"type": "integer",
"title": "Quantile",
"default": 50
}
},
"type": "object",
"required": [
"attribution_id"
],
"title": "ExcelPostAttribution",
"description": "Post attribution excel job."
},
{
"properties": {
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 90
},
"excel_type": {
"type": "string",
"const": "simulation",
"title": "Excel Type",
"default": "simulation"
},
"simulation_id": {
"type": "integer",
"title": "Simulation Id"
}
},
"type": "object",
"required": [
"simulation_id"
],
"title": "ExcelPostSimulation",
"description": "Post simulation excel job."
},
{
"properties": {
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 90
},
"excel_type": {
"type": "string",
"const": "prediction",
"title": "Excel Type",
"default": "prediction"
},
"prediction_id": {
"type": "integer",
"title": "Prediction Id"
}
},
"type": "object",
"required": [
"prediction_id"
],
"title": "ExcelPostPrediction",
"description": "Post prediction excel job."
},
{
"properties": {
"priority": {
"type": "integer",
"maximum": 100,
"exclusiveMinimum": 0,
"title": "The priority",
"description": "The priority value for the job.",
"default": 90
},
"excel_type": {
"type": "string",
"const": "optimization",
"title": "Excel Type",
"default": "optimization"
},
"optimization_id": {
"type": "integer",
"title": "Optimization Id"
}
},
"type": "object",
"required": [
"optimization_id"
],
"title": "ExcelPostOptimization",
"description": "Post optimization excel job."
}
],
"title": "Request"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"IId": {
"type": "integer",
"title": "Iid",
"description": "Internal identifier for the export job"
},
"JobId": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Jobid",
"description": "Background worker job ID for status tracking"
},
"Date": {
"type": "string",
"format": "date-time",
"title": "Date",
"description": "Export job creation timestamp"
},
"Status": {
"description": "Current job state: PENDING, RUNNING, COMPLETED, or FAILED",
"type": "string",
"enum": [
"pending",
"running",
"failed",
"saving_results",
"completed",
"processing_upload",
"submitted",
"stopped"
],
"title": "JobState"
},
"Type": {
"type": "string",
"title": "Type",
"description": "Export type identifier"
}
},
"type": "object",
"required": [
"IId",
"Date",
"Status",
"Type"
],
"title": "ExcelJobs",
"description": "Response schema for Excel export jobs."
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Bulk Delete Excel Jobs (/api/excel-jobs/bulk_delete_excel_jobs_projects__team_id___project_id__excel_delete)
Bulk delete Excel jobs matching the given filters.
Hard-deletes all matching jobs immediately and cancels their drun jobs
in the background in a single batch call.
## DELETE /api/projects/{team_id}/{project_id}/excel
Bulk Delete Excel Jobs
Bulk delete Excel jobs matching the given filters.
Hard-deletes all matching jobs immediately and cancels their drun jobs
in the background in a single batch call.
```json
{
"tags": [
"Excel Jobs"
],
"summary": "Bulk Delete Excel Jobs",
"description": "Bulk delete Excel jobs matching the given filters.\n\nHard-deletes all matching jobs immediately and cancels their drun jobs\nin the background in a single batch call.",
"operationId": "bulk_delete_excel_jobs_projects__team_id___project_id__excel_delete",
"deprecated": true,
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /.\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results. Same syntax as GET /.\n "
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Excel Export Task (/api/excel-jobs/delete_excel_export_task_projects__team_id___project_id__excel__excel_job_id__delete)
Delete an Excel job.
This endpoint deletes a specified Excel job.
## DELETE /api/projects/{team_id}/{project_id}/excel/{excel_job_id}
Delete Excel Export Task
Delete an Excel job.
This endpoint deletes a specified Excel job.
```json
{
"tags": [
"Excel Jobs"
],
"summary": "Delete Excel Export Task",
"description": "Delete an Excel job.\n\nThis endpoint deletes a specified Excel job.",
"operationId": "delete_excel_export_task_projects__team_id___project_id__excel__excel_job_id__delete",
"deprecated": true,
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
},
{
"name": "excel_job_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide excel job path.",
"title": "Excel Job Id"
},
"description": "Provide excel job path."
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Download Excel Export (/api/excel-jobs/download_excel_export_projects__team_id___project_id__excel__excel_job_id__output_get)
Get Excel job output.
This endpoint retrieves the output of a specified Excel job.
## GET /api/projects/{team_id}/{project_id}/excel/{excel_job_id}/output
Download Excel Export
Get Excel job output.
This endpoint retrieves the output of a specified Excel job.
```json
{
"tags": [
"Excel Jobs"
],
"summary": "Download Excel Export",
"description": "Get Excel job output.\n\nThis endpoint retrieves the output of a specified Excel job.",
"operationId": "download_excel_export_projects__team_id___project_id__excel__excel_job_id__output_get",
"deprecated": true,
"parameters": [
{
"name": "excel_job_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"description": "Provide excel job path.",
"title": "Excel Job Id"
},
"description": "Provide excel job path."
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "project_id",
"in": "path",
"required": true,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"description": "Use project Id or slug",
"title": "Project Id"
},
"description": "Use project Id or slug"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Ntfy Token (/api/notifications/get_ntfy_token_notification__team_id__ntfy_token_get)
Get a ntfy access token for the team.
Ensures a ntfy account exists for the team, then returns a short-lived
token the frontend can use to subscribe to job status notifications on
topics scoped to this team. The token is cached in Redis for most of its
TTL to avoid issuing a new token on every request.
## GET /api/notification/{team_id}/ntfy-token
Get Ntfy Token
Get a ntfy access token for the team.
Ensures a ntfy account exists for the team, then returns a short-lived
token the frontend can use to subscribe to job status notifications on
topics scoped to this team. The token is cached in Redis for most of its
TTL to avoid issuing a new token on every request.
```json
{
"tags": [
"Notifications"
],
"summary": "Get Ntfy Token",
"description": "Get a ntfy access token for the team.\n\nEnsures a ntfy account exists for the team, then returns a short-lived\ntoken the frontend can use to subscribe to job status notifications on\ntopics scoped to this team. The token is cached in Redis for most of its\nTTL to avoid issuing a new token on every request.",
"operationId": "get_ntfy_token_notification__team_id__ntfy_token_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Templates (/api/templates/list_templates_templates__team_id__get)
Get list of templates.
This endpoint retrieves a paginated list of templates based on the provided filters.
## GET /api/templates/{team_id}
List Templates
Get list of templates.
This endpoint retrieves a paginated list of templates based on the provided filters.
```json
{
"tags": [
"Templates"
],
"summary": "List Templates",
"description": "Get list of templates.\n\nThis endpoint retrieves a paginated list of templates based on the provided filters.",
"operationId": "list_templates_templates__team_id__get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
},
{
"name": "filters",
"in": "query",
"required": false,
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By name: filters='{\"Name\": [[\"contains\", \"Marketing Mix\"]]}'\n - Recent templates: filters='{\"CreatedDate\": [[\">=\", \"2024-01-01\"]]}'\n - Sort by date: filters='{\"CreatedDate\": [[\"orderby\", \"desc\"]]}'\n ",
"title": "Filters"
},
"description": "\n JSON filter expressions to narrow results.\n\n Examples:\n - By name: filters='{\"Name\": [[\"contains\", \"Marketing Mix\"]]}'\n - Recent templates: filters='{\"CreatedDate\": [[\">=\", \"2024-01-01\"]]}'\n - Sort by date: filters='{\"CreatedDate\": [[\"orderby\", \"desc\"]]}'\n "
},
{
"name": "page",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"description": "Page number",
"default": 1,
"title": "Page"
},
"description": "Page number"
},
{
"name": "size",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Page size",
"default": 50,
"title": "Size"
},
"description": "Page size"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"items": {
"items": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Graph": {
"additionalProperties": true,
"type": "object",
"title": "Graph"
}
},
"type": "object",
"required": [
"Id",
"CreatedDate",
"Graph"
],
"title": "Template",
"description": "Template response.",
"examples": [
{
"CreatedDate": "2024-01-15T10:30:00",
"CreatorId": "user-123",
"Graph": {
"edges": [
{
"arguments": [
"positive"
],
"source": "media",
"target": "sales"
}
],
"nodes": [
{
"id": "sales",
"key": "File:Sales",
"type": "Node.Data"
},
{
"id": "media",
"key": "File:Media",
"type": "Node.Data"
}
]
},
"Id": 1,
"Name": "Marketing Mix Model Template",
"Note": "Template for standard marketing mix analysis"
}
]
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"minimum": 0,
"title": "Total"
},
"page": {
"type": "integer",
"minimum": 1,
"title": "Page"
},
"size": {
"type": "integer",
"minimum": 1,
"title": "Size"
},
"pages": {
"type": "integer",
"minimum": 0,
"title": "Pages"
}
},
"type": "object",
"required": [
"items",
"total",
"page",
"size",
"pages"
],
"title": "Page[Template]"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Create Template (/api/templates/create_template_templates__team_id__post)
Create a template.
This endpoint creates a new template based on the provided request data.
## POST /api/templates/{team_id}
Create Template
Create a template.
This endpoint creates a new template based on the provided request data.
```json
{
"tags": [
"Templates"
],
"summary": "Create Template",
"description": "Create a template.\n\nThis endpoint creates a new template based on the provided request data.",
"operationId": "create_template_templates__team_id__post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Optional description or documentation for this resource."
},
"prefix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Prefix",
"description": "Prefix for the name."
},
"graph": {
"additionalProperties": true,
"type": "object",
"title": "Graph"
}
},
"type": "object",
"required": [
"graph"
],
"title": "CreateTemplate",
"description": "Schema for create template.",
"examples": [
{
"graph": {
"edges": [
{
"arguments": [
"positive"
],
"source": "media",
"target": "sales"
}
],
"nodes": [
{
"id": "sales",
"key": "File:Sales",
"type": "Node.Data"
},
{
"id": "media",
"key": "File:Media",
"type": "Node.Data"
}
]
},
"name": "Marketing Mix Model Template",
"note": "Template for standard marketing mix analysis"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Graph": {
"additionalProperties": true,
"type": "object",
"title": "Graph"
}
},
"type": "object",
"required": [
"Id",
"CreatedDate",
"Graph"
],
"title": "Template",
"description": "Template response.",
"examples": [
{
"CreatedDate": "2024-01-15T10:30:00",
"CreatorId": "user-123",
"Graph": {
"edges": [
{
"arguments": [
"positive"
],
"source": "media",
"target": "sales"
}
],
"nodes": [
{
"id": "sales",
"key": "File:Sales",
"type": "Node.Data"
},
{
"id": "media",
"key": "File:Media",
"type": "Node.Data"
}
]
},
"Id": 1,
"Name": "Marketing Mix Model Template",
"Note": "Template for standard marketing mix analysis"
}
]
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"405": {
"description": "Operation not permitted (limit reached or conflict)",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Template (/api/templates/get_template_templates__team_id___template_id__get)
Get a template.
This endpoint retrieves detailed information about a specific template.
## GET /api/templates/{team_id}/{template_id}
Get Template
Get a template.
This endpoint retrieves detailed information about a specific template.
```json
{
"tags": [
"Templates"
],
"summary": "Get Template",
"description": "Get a template.\n\nThis endpoint retrieves detailed information about a specific template.",
"operationId": "get_template_templates__team_id___template_id__get",
"parameters": [
{
"name": "template_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"title": "Template Id"
}
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Graph": {
"additionalProperties": true,
"type": "object",
"title": "Graph"
}
},
"type": "object",
"required": [
"Id",
"CreatedDate",
"Graph"
],
"title": "Template",
"description": "Template response.",
"examples": [
{
"CreatedDate": "2024-01-15T10:30:00",
"CreatorId": "user-123",
"Graph": {
"edges": [
{
"arguments": [
"positive"
],
"source": "media",
"target": "sales"
}
],
"nodes": [
{
"id": "sales",
"key": "File:Sales",
"type": "Node.Data"
},
{
"id": "media",
"key": "File:Media",
"type": "Node.Data"
}
]
},
"Id": 1,
"Name": "Marketing Mix Model Template",
"Note": "Template for standard marketing mix analysis"
}
]
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Template (/api/templates/update_template_templates__team_id___template_id__patch)
Patch template attributes.
This endpoint updates the attributes of an existing template based on
the provided update data.
## PATCH /api/templates/{team_id}/{template_id}
Update Template
Patch template attributes.
This endpoint updates the attributes of an existing template based on
the provided update data.
```json
{
"tags": [
"Templates"
],
"summary": "Update Template",
"description": "Patch template attributes.\n\nThis endpoint updates the attributes of an existing template based on\nthe provided update data.",
"operationId": "update_template_templates__team_id___template_id__patch",
"parameters": [
{
"name": "template_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"title": "Template Id"
}
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Custom name for the model/dataset. Name will be autogenerated if empty."
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note",
"description": "Description for the model/dataset"
},
"Graph": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Graph"
}
},
"type": "object",
"title": "PatchTemplate",
"description": "Schema for updating temptale.",
"examples": [
{
"graph": {
"edges": [],
"nodes": []
},
"name": "Updated Template Name",
"note": "Updated template description"
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"CreatorId": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creatorid"
},
"Id": {
"type": "integer",
"title": "Id"
},
"Name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"Note": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Note"
},
"CreatedDate": {
"type": "string",
"format": "date-time",
"title": "Createddate"
},
"Graph": {
"additionalProperties": true,
"type": "object",
"title": "Graph"
}
},
"type": "object",
"required": [
"Id",
"CreatedDate",
"Graph"
],
"title": "Template",
"description": "Template response.",
"examples": [
{
"CreatedDate": "2024-01-15T10:30:00",
"CreatorId": "user-123",
"Graph": {
"edges": [
{
"arguments": [
"positive"
],
"source": "media",
"target": "sales"
}
],
"nodes": [
{
"id": "sales",
"key": "File:Sales",
"type": "Node.Data"
},
{
"id": "media",
"key": "File:Media",
"type": "Node.Data"
}
]
},
"Id": 1,
"Name": "Marketing Mix Model Template",
"Note": "Template for standard marketing mix analysis"
}
]
}
}
}
},
"400": {
"description": "Invalid request - validation error or malformed data",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Template (/api/templates/delete_template_templates__team_id___template_id__delete)
Delete a template.
This endpoint deletes a specified template.
## DELETE /api/templates/{team_id}/{template_id}
Delete Template
Delete a template.
This endpoint deletes a specified template.
```json
{
"tags": [
"Templates"
],
"summary": "Delete Template",
"description": "Delete a template.\n\nThis endpoint deletes a specified template.",
"operationId": "delete_template_templates__team_id___template_id__delete",
"parameters": [
{
"name": "template_id",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"title": "Template Id"
}
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "Use team id",
"title": "Team Id"
},
"description": "Use team id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"404": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"type": "string",
"title": "Detail",
"description": "Human-readable error message"
}
},
"type": "object",
"required": [
"detail"
],
"title": "ErrorResponse",
"description": "Standard error response schema.",
"examples": [
{
"detail": "Resource not found"
}
]
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Bucket Config (/api/internal/get_bucket_config_internal_bucket_config_get)
Resolve S3 bucket config for drun and cache it in Redis.
Delegates to ``get_drun_config_by_id``: ``None`` -> legacy drun system
config; negative -> system bucket (no DB hit); positive -> tenant row.
Args:
team_id: The team identifier used for system-config cache key.
config_id: Stored bucket config id (None, negative system id, or
positive tenant row id).
Returns:
A dict with S3 bucket configuration fields.
## GET /api/internal/bucket-config
Get Bucket Config
Resolve S3 bucket config for drun and cache it in Redis.
Delegates to ``get_drun_config_by_id``: ``None`` -> legacy drun system
config; negative -> system bucket (no DB hit); positive -> tenant row.
Args:
team_id: The team identifier used for system-config cache key.
config_id: Stored bucket config id (None, negative system id, or
positive tenant row id).
Returns:
A dict with S3 bucket configuration fields.
```json
{
"tags": [
"Internal"
],
"summary": "Get Bucket Config",
"description": "Resolve S3 bucket config for drun and cache it in Redis.\n\nDelegates to ``get_drun_config_by_id``: ``None`` -> legacy drun system\nconfig; negative -> system bucket (no DB hit); positive -> tenant row.\n\nArgs:\n team_id: The team identifier used for system-config cache key.\n config_id: Stored bucket config id (None, negative system id, or\n positive tenant row id).\n\nReturns:\n A dict with S3 bucket configuration fields.",
"operationId": "get_bucket_config_internal_bucket_config_get",
"parameters": [
{
"name": "team_id",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Team ID to resolve config for",
"title": "Team Id"
},
"description": "Team ID to resolve config for"
},
{
"name": "config_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Stored bucket config id",
"title": "Config Id"
},
"description": "Stored bucket config id"
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List (/api/teams/list__teams_get)
List or search for multiple teams.
## GET /team/teams
List
List or search for multiple teams.
```json
{
"tags": [
"Teams"
],
"summary": "List ",
"description": "List or search for multiple teams.",
"operationId": "list__teams_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"items": {
"properties": {
"as_superadmin": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "As Superadmin"
},
"id": {
"type": "string",
"title": "Id"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"creation_time": {
"type": "string",
"format": "date-time",
"title": "Creation Time"
},
"creator_id": {
"type": "string",
"title": "Creator Id"
},
"max_members": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Members"
},
"suspended": {
"type": "boolean",
"title": "Suspended"
}
},
"type": "object",
"required": [
"id",
"name",
"description",
"creation_time",
"creator_id",
"max_members",
"suspended"
],
"title": "GetListTeamResponse",
"description": "Get team list response schema."
},
"type": "array",
"title": "Response List Teams Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get (/api/teams/get_teams__team_id__get)
Get detailed information on a single team.
## GET /team/teams/{team_id}
Get
Get detailed information on a single team.
```json
{
"tags": [
"Teams"
],
"summary": "Get",
"description": "Get detailed information on a single team.",
"operationId": "get_teams__team_id__get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Team Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"as_superadmin": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "As Superadmin"
},
"id": {
"type": "string",
"title": "Id"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"creation_time": {
"type": "string",
"format": "date-time",
"title": "Creation Time"
},
"creator_id": {
"type": "string",
"title": "Creator Id"
},
"max_members": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Members"
},
"suspended": {
"type": "boolean",
"title": "Suspended"
},
"memberships_count": {
"type": "integer",
"title": "Memberships Count"
},
"memberships": {
"items": {
"properties": {
"role": {
"type": "string",
"title": "Role"
},
"can_leave": {
"type": "boolean",
"title": "Can Leave"
},
"team_id": {
"type": "string",
"title": "Team Id"
},
"user_id": {
"type": "string",
"title": "User Id"
},
"join_date": {
"type": "string",
"format": "date-time",
"title": "Join Date"
}
},
"type": "object",
"required": [
"role",
"can_leave",
"team_id",
"user_id",
"join_date"
],
"title": "Membership",
"description": "Membership schema."
},
"type": "array",
"title": "Memberships"
}
},
"type": "object",
"required": [
"id",
"name",
"description",
"creation_time",
"creator_id",
"max_members",
"suspended",
"memberships_count",
"memberships"
],
"title": "GetCurrentTeamResponse",
"description": "Get team response schema."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update (/api/teams/update_teams__team_id__patch)
Update a team.
## PATCH /team/teams/{team_id}
Update
Update a team.
```json
{
"tags": [
"Teams"
],
"summary": "Update",
"description": "Update a team.",
"operationId": "update_teams__team_id__patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Team Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"title": "Updates"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
},
"creation_time": {
"type": "string",
"format": "date-time",
"title": "Creation Time"
},
"creator_id": {
"type": "string",
"title": "Creator Id"
},
"max_members": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Members"
},
"suspended": {
"type": "boolean",
"title": "Suspended"
},
"memberships_count": {
"type": "integer",
"title": "Memberships Count"
},
"memberships": {
"items": {
"properties": {
"role": {
"type": "string",
"title": "Role"
},
"can_leave": {
"type": "boolean",
"title": "Can Leave"
},
"team_id": {
"type": "string",
"title": "Team Id"
},
"user_id": {
"type": "string",
"title": "User Id"
},
"join_date": {
"type": "string",
"format": "date-time",
"title": "Join Date"
}
},
"type": "object",
"required": [
"role",
"can_leave",
"team_id",
"user_id",
"join_date"
],
"title": "Membership",
"description": "Membership schema."
},
"type": "array",
"title": "Memberships"
}
},
"type": "object",
"required": [
"id",
"name",
"description",
"creation_time",
"creator_id",
"max_members",
"suspended",
"memberships_count",
"memberships"
],
"title": "TeamWithMemberships",
"description": "Team schema with memberships."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete (/api/teams/delete_teams__team_id__delete)
Delete a team.
## DELETE /team/teams/{team_id}
Delete
Delete a team.
```json
{
"tags": [
"Teams"
],
"summary": "Delete",
"description": "Delete a team.",
"operationId": "delete_teams__team_id__delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Team Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Members (/api/teams/list_members_teams__team_id__member_get)
List members of a team with additional details from user service.
## GET /team/teams/{team_id}/member
List Members
List members of a team with additional details from user service.
```json
{
"tags": [
"Teams"
],
"summary": "List Members",
"description": "List members of a team with additional details from user service.",
"operationId": "list_members_teams__team_id__member_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Team Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"role": {
"type": "string",
"title": "Role"
},
"can_leave": {
"type": "boolean",
"title": "Can Leave"
},
"team_id": {
"type": "string",
"title": "Team Id"
},
"user_id": {
"type": "string",
"title": "User Id"
},
"join_date": {
"type": "string",
"format": "date-time",
"title": "Join Date"
},
"email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Email"
},
"username": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Username"
},
"picture": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Picture"
}
},
"type": "object",
"required": [
"role",
"can_leave",
"team_id",
"user_id",
"join_date"
],
"title": "MembershipWithDetails",
"description": "Membership schema with user details."
},
"title": "Response List Members Teams Team Id Member Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Add Member (/api/teams/add_member_teams__team_id__member_post)
Add a member to a team.
## POST /team/teams/{team_id}/member
Add Member
Add a member to a team.
```json
{
"tags": [
"Teams"
],
"summary": "Add Member",
"description": "Add a member to a team.",
"operationId": "add_member_teams__team_id__member_post",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Team Id"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"manager",
"modelbuilder",
"datamanager",
"member",
"observer"
],
"title": "Role",
"description": "Enum representing available roles."
},
"email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Email"
},
"user_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "User Id"
}
},
"type": "object",
"required": [
"role"
],
"title": "Body_add_member_teams__team_id__member_post"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"email": {
"type": "string",
"title": "Email"
},
"role": {
"type": "string",
"title": "Role"
},
"code": {
"type": "string",
"title": "Code"
},
"accepted": {
"type": "boolean",
"title": "Accepted"
},
"invited_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Invited By"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"expires_at": {
"type": "string",
"format": "date-time",
"title": "Expires At"
}
},
"type": "object",
"required": [
"id",
"email",
"role",
"code",
"accepted",
"created_at",
"expires_at"
],
"title": "Invitation",
"description": "Team invitation schema."
}
}
},
"description": "Created"
},
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Member Role (/api/teams/update_member_role_teams__team_id__member_patch)
Assign a new role to a team member.
## PATCH /team/teams/{team_id}/member
Update Member Role
Assign a new role to a team member.
```json
{
"tags": [
"Teams"
],
"summary": "Update Member Role",
"description": "Assign a new role to a team member.",
"operationId": "update_member_role_teams__team_id__member_patch",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Team Id"
}
},
{
"name": "user_id",
"in": "query",
"required": true,
"schema": {
"title": "User Id"
}
},
{
"name": "new_role",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"owner",
"admin",
"manager",
"modelbuilder",
"datamanager",
"member",
"observer"
],
"title": "Role",
"description": "Enum representing available roles."
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Remove Member (/api/teams/remove_member_teams__team_id__member_delete)
Remove a member from a team.
## DELETE /team/teams/{team_id}/member
Remove Member
Remove a member from a team.
```json
{
"tags": [
"Teams"
],
"summary": "Remove Member",
"description": "Remove a member from a team.",
"operationId": "remove_member_teams__team_id__member_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Team Id"
}
},
{
"name": "user_id",
"in": "query",
"required": true,
"schema": {
"title": "User Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Leave Team (/api/teams/leave_team_teams__team_id__leave_delete)
Leave your currently active team.
## DELETE /team/teams/{team_id}/leave
Leave Team
Leave your currently active team.
```json
{
"tags": [
"Teams"
],
"summary": "Leave Team",
"description": "Leave your currently active team.",
"operationId": "leave_team_teams__team_id__leave_delete",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Team Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Roles (/api/teams/get_roles_teams__team_id__roles_get)
Get all available roles and their permissions.
## GET /team/teams/{team_id}/roles
Get Roles
Get all available roles and their permissions.
```json
{
"tags": [
"Teams"
],
"summary": "Get Roles",
"description": "Get all available roles and their permissions.",
"operationId": "get_roles_teams__team_id__roles_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Team Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"role": {
"type": "string",
"title": "Role"
},
"permissions": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Permissions"
}
},
"type": "object",
"required": [
"role"
],
"title": "RoleDescription",
"description": "Role description schema."
},
"title": "Response Get Roles Teams Team Id Roles Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# List Invitations (/api/manage-invitations/list_invitations_teams__team_id__invitations_get)
List all team invitations.
## GET /team/teams/{team_id}/invitations
List Invitations
List all team invitations.
```json
{
"tags": [
"Manage Invitations"
],
"summary": "List Invitations",
"description": "List all team invitations.",
"operationId": "list_invitations_teams__team_id__invitations_get",
"parameters": [
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Team Id"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"email": {
"type": "string",
"title": "Email"
},
"role": {
"type": "string",
"title": "Role"
},
"code": {
"type": "string",
"title": "Code"
},
"accepted": {
"type": "boolean",
"title": "Accepted"
},
"invited_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Invited By"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"expires_at": {
"type": "string",
"format": "date-time",
"title": "Expires At"
}
},
"type": "object",
"required": [
"id",
"email",
"role",
"code",
"accepted",
"created_at",
"expires_at"
],
"title": "Invitation",
"description": "Team invitation schema."
},
"title": "Response List Invitations Teams Team Id Invitations Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update Invitation (/api/manage-invitations/update_invitation_teams__team_id__invitations__invitation_id__patch)
Update a team invitation's role.
## PATCH /team/teams/{team_id}/invitations/{invitation_id}
Update Invitation
Update a team invitation's role.
```json
{
"tags": [
"Manage Invitations"
],
"summary": "Update Invitation",
"description": "Update a team invitation's role.",
"operationId": "update_invitation_teams__team_id__invitations__invitation_id__patch",
"parameters": [
{
"name": "invitation_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Invitation Id"
}
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Team Id"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"role": {
"anyOf": [
{
"type": "string",
"enum": [
"owner",
"admin",
"manager",
"modelbuilder",
"datamanager",
"member",
"observer"
],
"title": "Role",
"description": "Enum representing available roles."
},
{
"type": "null"
}
]
},
"renew": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Renew",
"default": false
}
},
"type": "object",
"title": "Body_update_invitation_teams__team_id__invitations__invitation_id__patch"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"email": {
"type": "string",
"title": "Email"
},
"role": {
"type": "string",
"title": "Role"
},
"code": {
"type": "string",
"title": "Code"
},
"accepted": {
"type": "boolean",
"title": "Accepted"
},
"invited_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Invited By"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"expires_at": {
"type": "string",
"format": "date-time",
"title": "Expires At"
}
},
"type": "object",
"required": [
"id",
"email",
"role",
"code",
"accepted",
"created_at",
"expires_at"
],
"title": "Invitation",
"description": "Team invitation schema."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete Invitation (/api/manage-invitations/delete_invitation_teams__team_id__invitations__invitation_id__delete)
Delete a team invitation.
## DELETE /team/teams/{team_id}/invitations/{invitation_id}
Delete Invitation
Delete a team invitation.
```json
{
"tags": [
"Manage Invitations"
],
"summary": "Delete Invitation",
"description": "Delete a team invitation.",
"operationId": "delete_invitation_teams__team_id__invitations__invitation_id__delete",
"parameters": [
{
"name": "invitation_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Invitation Id"
}
},
{
"name": "team_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Team Id"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Invitation (/api/invitations/get_invitation_invitations__code__get)
Get a team invitation.
## GET /team/invitations/{code}
Get Invitation
Get a team invitation.
```json
{
"tags": [
"Invitations"
],
"summary": "Get Invitation",
"description": "Get a team invitation.",
"operationId": "get_invitation_invitations__code__get",
"parameters": [
{
"name": "code",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Code"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"role": {
"type": "string",
"title": "Role"
},
"code": {
"type": "string",
"title": "Code"
},
"team": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
}
},
"type": "object",
"required": [
"id",
"name"
],
"title": "TeamDescription",
"description": "Team description schema."
},
"expires_at": {
"type": "string",
"format": "date-time",
"title": "Expires At"
},
"accepted": {
"type": "boolean",
"title": "Accepted"
}
},
"type": "object",
"required": [
"id",
"role",
"code",
"team",
"expires_at",
"accepted"
],
"title": "UserInvitation",
"description": "User invitation schema."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Accept Invitation (/api/invitations/accept_invitation_invitations__code__post)
Accept a team invitation.
## POST /team/invitations/{code}
Accept Invitation
Accept a team invitation.
```json
{
"tags": [
"Invitations"
],
"summary": "Accept Invitation",
"description": "Accept a team invitation.",
"operationId": "accept_invitation_invitations__code__post",
"parameters": [
{
"name": "code",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Code"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"role": {
"type": "string",
"title": "Role"
},
"code": {
"type": "string",
"title": "Code"
},
"team": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
}
},
"type": "object",
"required": [
"id",
"name"
],
"title": "TeamDescription",
"description": "Team description schema."
},
"expires_at": {
"type": "string",
"format": "date-time",
"title": "Expires At"
},
"accepted": {
"type": "boolean",
"title": "Accepted"
}
},
"type": "object",
"required": [
"id",
"role",
"code",
"team",
"expires_at",
"accepted"
],
"title": "UserInvitation",
"description": "User invitation schema."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Decline Invitation (/api/invitations/decline_invitation_invitations__code__delete)
Decline a team invitation.
## DELETE /team/invitations/{code}
Decline Invitation
Decline a team invitation.
```json
{
"tags": [
"Invitations"
],
"summary": "Decline Invitation",
"description": "Decline a team invitation.",
"operationId": "decline_invitation_invitations__code__delete",
"parameters": [
{
"name": "code",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Code"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Invitations (/api/invitations/get_invitations_invitations_get)
Get all team invitations for a user.
## GET /team/invitations
Get Invitations
Get all team invitations for a user.
```json
{
"tags": [
"Invitations"
],
"summary": "Get Invitations",
"description": "Get all team invitations for a user.",
"operationId": "get_invitations_invitations_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"items": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"role": {
"type": "string",
"title": "Role"
},
"code": {
"type": "string",
"title": "Code"
},
"team": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description"
}
},
"type": "object",
"required": [
"id",
"name"
],
"title": "TeamDescription",
"description": "Team description schema."
},
"expires_at": {
"type": "string",
"format": "date-time",
"title": "Expires At"
},
"accepted": {
"type": "boolean",
"title": "Accepted"
}
},
"type": "object",
"required": [
"id",
"role",
"code",
"team",
"expires_at",
"accepted"
],
"title": "UserInvitation",
"description": "User invitation schema."
},
"type": "array",
"title": "Response Get Invitations Invitations Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Health Check (/api/health/health_check_health_get)
Basic liveness check.
Returns 200 OK if the service is running.
Use this for Kubernetes liveness probes.
## GET /user/health
Health Check
Basic liveness check.
Returns 200 OK if the service is running.
Use this for Kubernetes liveness probes.
```json
{
"tags": [
"Health"
],
"summary": "Health Check",
"description": "Basic liveness check.\n\nReturns 200 OK if the service is running.\nUse this for Kubernetes liveness probes.",
"operationId": "health_check_health_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
```
# Readiness Check (/api/health/readiness_check_ready_get)
Readiness check with dependency verification.
Verifies database and Redis connectivity.
Use this for Kubernetes readiness probes.
## GET /user/ready
Readiness Check
Readiness check with dependency verification.
Verifies database and Redis connectivity.
Use this for Kubernetes readiness probes.
```json
{
"tags": [
"Health"
],
"summary": "Readiness Check",
"description": "Readiness check with dependency verification.\n\nVerifies database and Redis connectivity.\nUse this for Kubernetes readiness probes.",
"operationId": "readiness_check_ready_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
```
# Get User Tokens (/api/access-token/get_user_tokens_access_tokens_get)
Get user tokens.
## GET /user/access_tokens
Get User Tokens
Get user tokens.
```json
{
"tags": [
"Access Token"
],
"summary": "Get User Tokens",
"description": "Get user tokens.",
"operationId": "get_user_tokens_access_tokens_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"items": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"expires_at": {
"type": "string",
"format": "date-time",
"title": "Expires At"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Used At"
}
},
"type": "object",
"required": [
"id",
"name",
"created_at",
"expires_at"
],
"title": "AccessToken",
"description": "Access token schema."
},
"type": "array",
"title": "Response Get User Tokens Access Tokens Get"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Create User Token (/api/access-token/create_user_token_access_tokens_post)
Create user token.
## POST /user/access_tokens
Create User Token
Create user token.
```json
{
"tags": [
"Access Token"
],
"summary": "Create User Token",
"description": "Create user token.",
"operationId": "create_user_token_access_tokens_post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"expires_at": {
"type": "string",
"format": "date-time",
"title": "Expires At"
}
},
"type": "object",
"required": [
"name",
"expires_at"
],
"title": "CreateAccessTokenBody",
"description": "Create token request."
}
}
},
"required": true
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"id": {
"type": "string",
"format": "uuid",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
},
"expires_at": {
"type": "string",
"format": "date-time",
"title": "Expires At"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Last Used At"
},
"generated_token": {
"type": "string",
"title": "Generated Token"
}
},
"type": "object",
"required": [
"id",
"name",
"created_at",
"expires_at",
"generated_token"
],
"title": "CreateAccessTokenResponse",
"description": "Create token response."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Revoke User Token (/api/access-token/revoke_user_token_access_tokens__token_id__delete)
Revoke user token.
## DELETE /user/access_tokens/{token_id}
Revoke User Token
Revoke user token.
```json
{
"tags": [
"Access Token"
],
"summary": "Revoke User Token",
"description": "Revoke user token.",
"operationId": "revoke_user_token_access_tokens__token_id__delete",
"parameters": [
{
"name": "token_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Token Id"
}
}
],
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Get Current User (/api/user/get_current_user_current_get)
Get current user.
## GET /user/current
Get Current User
Get current user.
```json
{
"tags": [
"User"
],
"summary": "Get Current User",
"description": "Get current user.",
"operationId": "get_current_user_current_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"user_id": {
"type": "string",
"title": "User Id"
},
"email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Email"
},
"username": {
"type": "string",
"title": "Username"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"picture": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Picture"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
}
},
"type": "object",
"required": [
"user_id",
"username",
"created_at"
],
"title": "User",
"description": "User response schema."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Update (/api/user/update_current_patch)
Update current user.
## PATCH /user/current
Update
Update current user.
```json
{
"tags": [
"User"
],
"summary": "Update",
"description": "Update current user.",
"operationId": "update_current_patch",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"name": {
"anyOf": [
{
"type": "string",
"maxLength": 255,
"minLength": 3
},
{
"type": "null"
}
],
"title": "Name",
"description": "User name"
},
"username": {
"anyOf": [
{
"type": "string",
"maxLength": 100,
"minLength": 3
},
{
"type": "null"
}
],
"title": "Username"
},
"password": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Password"
},
"picture": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Picture",
"description": "Base64 encoded image"
}
},
"type": "object",
"title": "UpdateUserBody",
"description": "Update user request body."
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"user_id": {
"type": "string",
"title": "User Id"
},
"email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Email"
},
"username": {
"type": "string",
"title": "Username"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"picture": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Picture"
},
"created_at": {
"type": "string",
"format": "date-time",
"title": "Created At"
}
},
"type": "object",
"required": [
"user_id",
"username",
"created_at"
],
"title": "User",
"description": "User response schema."
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```
# Delete (/api/user/delete_current_delete)
Delete current user.
## DELETE /user/current
Delete
Delete current user.
```json
{
"tags": [
"User"
],
"summary": "Delete",
"description": "Delete current user.",
"operationId": "delete_current_delete",
"responses": {
"204": {
"description": "Successful Response"
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
}
}
}
}
}
```