> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/use-cases.md).

# Use Cases

Group Vision Events by purpose using Use Cases.

## About

A Use Case groups [Vision Events](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events.md) that share a common purpose and custom metadata structure, and every event belongs to exactly one Use Case. Organizing events this way makes it easy to filter and compare data across cameras, devices, and locations that report the same fields.

Put events in the same Use Case when they share custom metadata fields, even if they come from different locations, cameras, or devices. For example, a "Defect Detection" Use Case might receive events from several factories, all with `line_id`, `shift`, and `part_number`. Create separate Use Cases when the metadata structure is different:

* Assembly Line QA: `line_id`, `shift`, `part_number`
* Warehouse Inventory: `aisle`, `shelf`, `item_type`
* Construction Site Safety: `zone`, `alert_type`, `contractor`

After events arrive, Roboflow infers a custom metadata schema from the fields and value types it sees. To see it, call [Get Custom Metadata Schema](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/get-custom-metadata-schema.md).

The [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) creates a Use Case when it builds a Workflow with Vision Events. It reuses an existing Use Case if one fits. You can also ask it to set one up.

Archiving a Use Case hides it from the default view. Its events are kept, and you can unarchive it. Events sent to an archived Use Case are still stored, but each returns a warning.

### Event Value

Give events a money value to track what a Use Case is worth (ex: the cost of each defect caught). Set a default value and currency on the Use Case. New events that don't send their own value get the default; events you already sent keep their value.

An event can also send its own value in `valueBaseUnits` (see [Create a Vision Event](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/create-a-vision-event.md#http-api)). The value is always in the Use Case currency. Value totals update about every 5 minutes.

### Checklists

A checklist tracks the steps a unit must pass at a station (ex: four screws on a board). Each checklist has a name and a list of items. A Use Case can have up to 20 checklists, each with up to 50 items. Roboflow reads checklist status from your `quality_check` events. It does not store a separate status.

Each unit gets one window. Send these `customMetadata` keys on every `quality_check` event for the unit:

* `checklistId`: the checklist's ID.
* `checklistWindowId`: one ID per unit (ex: its serial number). Every event for that unit uses the same ID.
* `checklistRole`: `window_open`, `item`, or `window_close`.
* `checklistItemId`: the item the result is for. Send it on `item` events only.

On an `item` event, set `eventData.result` to `pass` or `fail`. Give each event its own `eventId`. An event with the same `eventId`, `timestamp`, and `useCaseId` replaces the earlier one.

Turn on "Require Order" (`ordered` in the API) to make items pass in order. Then a pass counts only when every earlier item has passed, and a fail clears that item and every item after it. Without it, items pass in any order and a later fail does not clear a pass.

## Web App

Open "Vision Events" in the left sidebar of your Workspace and click "+ Create Use Case".

<figure><img src="https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-e940058d52aa94761417871f65f91eaf3772b31e%2Fimage%20(456).png?alt=media" alt="" width="375"><figcaption></figcaption></figure>

The Use Cases table shows each Use Case's event count, last event time, event types, and all-time value. A Use Case's Overview shows its value in the "Value Created" tile.

To set a default [event value](#event-value), open a Use Case's menu, click "Update Settings", and fill in "Default Event Value" and "Currency".

To add [checklists](#checklists), open a Use Case's menu, click "Edit Checklists", then click "Add Checklist". Click "Save Checklists" to store your changes. To see each unit's progress, open the Use Case and click the "Checklists" tab. The Connect Guide shows sample checklist events with your checklist IDs.

You can archive a Use Case from the dashboard. Click "View archived use cases" at the bottom of the table to see archived ones.

<figure><img src="https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-a19e941a3d1c11eebe09fc1426edc618aef53913%2FDashboard%20view%20for%20solution%20nine%20status.png?alt=media" alt=""><figcaption></figcaption></figure>

## HTTP API

Unrestricted Workspace API keys have the `vision-events:manage` scope by default.

### Create a Use Case

Create a new use case in your workspace. Use cases help you organize vision events by deployment context (e.g., "Manufacturing Line 1", "Warehouse Inventory").

**Required scope:** `vision-events:manage`

{% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events/use-cases" method="post" %}
[openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### Notes

* New use cases are created with an `active` status by default.
* After creating a use case, you can reference its `id` as the `useCaseId` when [creating vision events](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/create-a-vision-event.md#http-api).

### Update a Use Case

Update the name, status, default event value, or checklists of an existing use case. Sending `checklists` replaces all of the use case's checklists.

**Required scope:** `vision-events:manage`

{% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events/use-cases/{useCaseId}" method="put" %}
[openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### List Use Cases

List the use cases in your workspace. To learn how to create and manage use cases, see the [Use Cases documentation](https://docs.roboflow.com/deployment/monitoring-and-analytics/vision-events/use-cases.md).

**Required scope:** `vision-events:read` or `device:read`

{% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events/use-cases" method="get" %}
[openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Archive a Use Case

Archive a use case by setting its status to `inactive`. Archived use cases are hidden from listings by default. Events sent to an archived use case are still stored, with an `entity_not_found` warning.

**Required scope:** `vision-events:manage`

{% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events/use-cases/{useCaseId}/archive" method="post" %}
[openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### Notes

* Archiving is a soft delete. The use case and its events are preserved but hidden from active listings.
* To view archived use cases, use the [List Use Cases](#http-api) endpoint with `status=inactive`.
* You can restore an archived use case using the [Unarchive a Use Case](#http-api) endpoint.

### Unarchive a Use Case

Restore a previously archived use case by setting its status back to `active`.

**Required scope:** `vision-events:manage`

{% openapi src="/files/sCDP9kVopV4JkkRK7GDd" path="/vision-events/use-cases/{useCaseId}/unarchive" method="post" %}
[openapi.yaml](https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-0988c6c6c600d725f72d1ecfe0cbeba9b717363f%2Fopenapi.yaml?alt=media)
{% endopenapi %}

#### Notes

* Only use cases with an `inactive` status can be unarchived.
* Once unarchived, the use case appears in active listings again, and new events no longer return the warning.

## Python SDK

Each vision event is associated with a use case. The Python SDK provides methods to create, list, rename, archive, and unarchive use cases.

### List Use Cases

```python
import roboflow

roboflow.login()

rf = roboflow.Roboflow()
ws = rf.workspace()

result = ws.list_vision_event_use_cases()

for uc in result["useCases"]:
    print(uc["id"], uc["name"], uc.get("status"))
```

You can filter by status:

```python
# List only active use cases
result = ws.list_vision_event_use_cases(status="active")
```

### Create a Use Case

```python
result = ws.create_vision_event_use_case("manufacturing-qa")
use_case_id = result["id"]
print(f"Created use case: {use_case_id}")
```

### Rename a Use Case

```python
ws.rename_vision_event_use_case("a1b3c8e1", "updated-name")
```

### Archive a Use Case

```python
ws.archive_vision_event_use_case("a1b3c8e1")
```

### Unarchive a Use Case

```python
ws.unarchive_vision_event_use_case("a1b3c8e1")
```

For more details on use case management, see the [REST API reference](#http-api).

## MCP Server

Connect your AI agent to the [MCP Server](https://docs.roboflow.com/agents/mcp-server) and it can manage use cases with these tools:

<table data-search="false"><thead><tr><th width="290">Tool</th><th>Description</th></tr></thead><tbody><tr><td><code>vision_events_use_cases_list</code></td><td>List the vision event use cases in the workspace.</td></tr><tr><td><code>vision_events_use_case_create</code></td><td>Create a new vision event use case.</td></tr><tr><td><code>vision_events_use_case_rename</code></td><td>Rename an existing use case.</td></tr><tr><td><code>vision_events_use_case_archive</code></td><td>Archive a use case.</td></tr><tr><td><code>vision_events_use_case_unarchive</code></td><td>Restore a previously archived use case.</td></tr></tbody></table>
