# Use cases

> Use cases - Use Cases are folder-like containers in DataRobot Workbench that allow you to group all
> assets related to solving a specific business problem inside of a single, manageable entity. These
> assets include datasets, models, experiments, No-Code AI Apps, and notebooks. You can share entire
> Use Cases or the individual assets they contain.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-05-01T23:10:47.766214+00:00` (UTC).

## Primary page

- [Use cases](https://docs.datarobot.com/en/docs/api/dev-learning/python/use_cases/use_cases.html): Full documentation for this topic (HTML).

## Sections on this page

- [Overview](https://docs.datarobot.com/en/docs/api/dev-learning/python/use_cases/use_cases.html#overview): In-page section heading.
- [Examples](https://docs.datarobot.com/en/docs/api/dev-learning/python/use_cases/use_cases.html#examples): In-page section heading.

## Related documentation

- [Developer documentation](https://docs.datarobot.com/en/docs/api/index.html): Linked from this page.
- [Developer learning](https://docs.datarobot.com/en/docs/api/dev-learning/index.html): Linked from this page.
- [Python API client user guide](https://docs.datarobot.com/en/docs/api/dev-learning/python/index.html): Linked from this page.
- [Use Cases](https://docs.datarobot.com/en/docs/api/dev-learning/python/use_cases/index.html): Linked from this page.
- [refer to the Workbench documentation.](https://docs.datarobot.com/en/docs/workbench/nxt-workbench/index.html): Linked from this page.
- [UseCaseReferenceEntity](https://docs.datarobot.com/en/docs/api/reference/sdk/use-cases.html#datarobot.models.use_cases.use_case.UseCaseReferenceEntity): Linked from this page.
- [datarobot.models.sharing.SharingRole](https://docs.datarobot.com/en/docs/api/reference/sdk/data-registry.html#datarobot.models.sharing.SharingRole): Linked from this page.

## Documentation content

# Use Cases

Use Cases are folder-like containers in DataRobot Workbench that allow you to group all assets related to solving a specific business problem inside of a single, manageable entity. These assets include datasets, models, experiments, No-Code AI Apps, and notebooks. You can share entire Use Cases or the individual assets they contain.

The primary benefit of a Use Case is that it enables experiment-based, iterative workflows. By housing all key insights in a single location, data scientists have improved navigation of assets and a cleaner interface for experiment creation and model training, review, and evaluation.

Specifically, Use Cases allow you to:

- Organize your work — group all related datasets, experiments, notebooks, etc. by the problem they solve.
- Find assets easily. Use Cases eliminate the need to search through hundreds of unrelated projects or scrape emails for hyperlinks to specific assets.
- Share collections of assets. You can share entire Use Cases, containing all the assets your team needs to participate.
- Manage access. Add or remove members to a Use Case to control their access.
- Monitor changes. Receive notifications when a team member adds, removes, or modifies any asset in a Use Case.

Currently, Use Cases in the Python client support interactions with binary classification and regression projects, applications, and datasets. Development is ongoing, so see the release notes for a full list of supported capabilities.

For a more in-depth look at Use Cases and the DataRobot Workbench, [refer to the Workbench documentation.](https://docs.datarobot.com/en/docs/workbench/nxt-workbench/index.html)

# Add to a Use Case

Currently, only project, dataset, and application instances can be added to a Use Case via the Python client.

The process of adding a dataset is shown in the example below:

```
import datarobot as dr

dr.Client(token="<token>", endpoint="https://app.datarobot.com/api/v2")

risk_use_case = dr.UseCase.create(
    name="Financial Risk Experimentation Environment",
    description="For running experiments on modeling financial risks to our business.",
)

new_dataset = dr.Dataset.create_from_file(
    file_path="/foo/bar/risk_data.csv",
)

risk_use_case.add(entity=new_dataset)

risk_use_case.list_datasets()
>>> [Dataset(name='risk_data.csv', id='646e8bb507b108ce7b474b27')]
```

You can add an application to a Use Case in a similar way. The primary difference is that you cannot create applications with the Python client. Instead, retrieve an application using its ID or pull it from a retrieved list of applications and then add it to a Use Case:

```
import datarobot as dr

dr.Client(token="<token>", endpoint="https://app.datarobot.com/api/v2")

risk_use_case = dr.UseCase.create(
    name="Financial Risk Experimentation Environment",
    description="For running experiments on modeling financial risks to our business.",
)

existing_application = dr.Application.list()[0]

risk_use_case.add(entity=existing_application)

risk_use_case.list_applications()
>>> [Application(name='Financial Risk Detection')]
```

Alternatively, the [UseCaseReferenceEntity](https://docs.datarobot.com/en/docs/api/reference/sdk/use-cases.html#datarobot.models.use_cases.use_case.UseCaseReferenceEntity) returned from [UseCase.add](https://docs.datarobot.com/en/docs/api/reference/sdk/use-cases.html#datarobot.UseCase.add) can be used to share an entity between Use Cases:

```
import datarobot as dr

dr.Client(token="<token>", endpoint="https://app.datarobot.com/api/v2")

risk_use_case_1 = dr.UseCase.create(
    name="Financial Risk Experimentation Environment",
    description="For running experiments on modeling financial risks to our business.",
)

risk_use_case_2 = dr.UseCase.create(
    name="Financial Risk Experimentation Environment 2",
    description="For running experiments on modeling financial risks to our business.",
)

new_dataset = dr.Dataset.create_from_file(
    file_path="/foo/bar/risk_data.csv",
)

dataset_entity = risk_use_case_1.add(entity=new_dataset)
risk_use_case_2.add(entity=dataset_entity)

risk_use_case_2.list_datasets()
>>> [Dataset(name='risk_data.csv', id='646e8bb507b108ce7b474b27')]
```

To add a project to a Use Case, it must meet the following conditions:

- It must be binary classification or regression project
- The associated dataset must be linked to the same Use Case
- Modeling must be in progress (via UI, the analyze_and_model method, or any other methods that initiate modeling)

```
import datarobot as dr

dr.Client(token="<token>", endpoint="https://app.datarobot.com/api/v2")

risk_use_case = dr.UseCase.create(
    name="Financial Risk Experimentation Environment",
    description="For running experiments on modeling financial risks to our business.",
)

new_dataset = dr.Dataset.create_from_file(
    file_path="/foo/bar/risk_data.csv",
    use_case=risk_use_case
)

risk_use_case.add(entity=new_dataset)

new_project = dr.Project.create_from_dataset(
    dataset_id=new_dataset.dataset_id,
    project_name="Risk Assessment v1",
    use_case=risk_use_case
)
new_project.analyze_and_model(target="credit_risk")

risk_use_case.add(entity=new_project)

risk_use_case.list_projects()
>>> [Project(Risk Assessment v1)]
risk_use_case.list_datasets()
>>> [Dataset(name='risk_data.csv', id='646e8bb507b108ce7b474b27')]
```

# Configuration

There are three primary ways of adding new projects or datasets to Use Cases once they’ve been generated.

1. The easiest method is to directly pass a Use Case to one of the project or dataset creation methods. Passing the use case directly allows for you to finely control what is added to a Use Case in your code. For example, the following code example creates a new Use Case, then creates a new project that is automatically added to the Use Case.

```
import datarobot as dr

dr.Client(token="<token>", endpoint="https://app.datarobot.com/api/v2")

risk_use_case = dr.UseCase.create(
    name="Financial Risk Experimentation Environment",
    description="For running experiments on modeling financial risks to our business.",
)

new_project = dr.Project.create(
    sourcedata="/foo/bar/risk_data.csv",
    project_name="Risk Assessment v1",
    use_case=risk_use_case
)

risk_use_case.list_projects()
>>> [Project(Risk Assessment v1)]
```

1. You can also use a context manager to perform a series of actions that automatically result in projects or datasets being added to a Use Case without having to manually pass the Use Case yourself. This can be extremely useful if you have a series of calls you want to make that all should be added to a Use Case. For example:

```
import datarobot as dr

dr.Client(token="<token>", endpoint="https://app.datarobot.com/api/v2")

risk_use_case = dr.UseCase.create(
    name="Financial Risk Experimentation Environment",
    description="For running experiments on modeling financial risks to our business.",
)

with risk_use_case:
    new_dataset = dr.Dataset.create_from_file(
        file_path="/foo/bar/risk_data.csv",
    )

risk_use_case.list_datasets()
>>> [Dataset(name='risk_data.csv', id='646e8bb507b108ce7b474b27')]
```

1. You can also set a global Use Case to automatically add all project and dataset instances that are created by your code. This is useful if all of the work you are doing should be contained in a single Use Case, but risks accidentally adding projects and datasets that should not be included in your Use Case. Setting a global default Use Case requires knowing the ID of your Use Case ahead of time. For example:

```
import datarobot as dr

dr.Client(token="<token>", endpoint="https://app.datarobot.com/api/v2", default_use_case="639ce542862e9b1b1bfa8f1b")

new_dataset = dr.Dataset.create_from_file(file_path="/foo/bar/risk_data.csv")

risk_use_case = dr.UseCase.get(id="639ce542862e9b1b1bfa8f1b")
risk_use_case.list_datasets()
>>> [Dataset(name='risk_data.csv', id='646e8bb507b108ce7b474b27')]
```

# Sharing

## Overview

Instances of [datarobot.models.sharing.SharingRole](https://docs.datarobot.com/en/docs/api/reference/sdk/data-registry.html#datarobot.models.sharing.SharingRole) can be created to define a new role grant (or revocation).

The [UseCase.share()](https://docs.datarobot.com/en/docs/api/reference/sdk/use-cases.html#datarobot.UseCase.share) instance method takes a list of [SharingRole](https://docs.datarobot.com/en/docs/api/reference/sdk/data-registry.html#datarobot.models.sharing.SharingRole) as its only argument.
Calling this method will apply the list of [SharingRoles](https://docs.datarobot.com/en/docs/api/reference/sdk/data-registry.html#datarobot.models.sharing.SharingRole) to the given [UseCase](https://docs.datarobot.com/en/docs/api/reference/sdk/use-cases.html#datarobot.UseCase).

Use Cases support `SHARING_ROLE.OWNER`, `SHARING_ROLE.EDITOR`, `SHARING_ROLE.CONSUMER` and `SHARING_ROLE.NO_ROLE` as possible `role` designations (see `datarobot.enums.SHARING_ROLE`).
Currently, the only supported `SHARING_RECIPIENT_TYPE` is `USER`.

## Examples

Suppose you had a list of user IDs you wanted to share this Use Case with.
You could use a loop to generate a list of SharingRole objects for them, and bulk share this Use Case.

```
>>> from datarobot.models.use_cases.use_case import UseCase
>>> from datarobot.models.sharing import SharingRole
>>> from datarobot.enums import SHARING_ROLE, SHARING_RECIPIENT_TYPE
>>>
>>> user_ids = ["60912e09fd1f04e832a575c1", "639ce542862e9b1b1bfa8f1b", "63e185e7cd3a5f8e190c6393"]
>>> sharing_roles = []
>>> for user_id in user_ids:
...     new_sharing_role = SharingRole(
...         role=SHARING_ROLE.CONSUMER,
...         share_recipient_type=SHARING_RECIPIENT_TYPE.USER,
...         id=user_id,
...         can_share=True,
...     )
...     sharing_roles.append(new_sharing_role)
>>> use_case = UseCase.get(use_case_id="5f33f1fd9071ae13568237b2")
>>> use_case.share(roles=sharing_roles)
```

Similarly, a [SharingRole](https://docs.datarobot.com/en/docs/api/reference/sdk/data-registry.html#datarobot.models.sharing.SharingRole) instance can be used to remove a user’s access if the `role` is set to `SHARING_ROLE.NO_ROLE`, like in this example:

```
>>> from datarobot.models.use_cases.use_case import UseCase
>>> from datarobot.models.sharing import SharingRole
>>> from datarobot.enums import SHARING_ROLE, SHARING_RECIPIENT_TYPE
>>>
>>> user_to_remove = "foo.bar@datarobot.com"
... remove_sharing_role = SharingRole(
...     role=SHARING_ROLE.NO_ROLE,
...     share_recipient_type=SHARING_RECIPIENT_TYPE.USER,
...     username=user_to_remove,
...     can_share=False,
... )
>>> use_case = UseCase.get(use_case_id="5f33f1fd9071ae13568237b2")
>>> use_case.share(roles=[remove_sharing_role])
```

# Looking beyond a Use Case

Use Cases are a powerful tool for organizing your work, and can help if you need to focus only on those resources relevant to a specific business problem.
However, occasionally you may want to look outside of a Use Case at other available DataRobot resources.
The following code snippet demonstrates how to retrieve all Projects that your user has access to:

```
import datarobot as dr
from datarobot.client import client_configuration

with client_configuration(default_use_case=[]):
    all_projects = dr.Project.list()
```