# Use Cases

## Use Cases

A Use Case groups Vision Events that share a common purpose and custom metadata structure. Every event belongs to exactly one Use Case. Events in the same Use Case typically share the same metadata fields, making it easy to filter and compare data across different sources.

### When to Use One vs. Multiple Use Cases

**Put events in the same Use Case** when they share similar custom metadata fields even if they come from different locations, cameras, or devices. For example, a "Defect Detection" Use Case might receive events from multiple factories, but all events include `line_id`, `shift`, and `part_number`.

**Create separate Use Cases** when the metadata structure is fundamentally different. For example:

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

### Create a Use Case

#### In the Dashboard

1. Navigate to **Vision Events** in the left sidebar of your workspace
2. Click **+ Create Use Case**
3. Enter a name for the Use Case

<figure><img src="https://662926385-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M6S9nPJhEX9FYH6clfW%2Fuploads%2FHeINTZfy9moBciMlrQpZ%2Fimage.png?alt=media&#x26;token=75581e01-5e61-46b4-958d-654ffb7014ac" alt="" width="375"><figcaption></figcaption></figure>

You can also create Use Cases via the REST API, see [Manage Use Cases Programmatically](#manage-use-cases-programmatically).

### View Use Cases

#### In the Dashboard

The Vision Events page displays a table of all your Use Cases, showing:

* Use Case name
* Total event count
* Last event timestamp
* Event types in use

#### Via the API

Retrieve all Use Cases in your workspace:

```bash
curl -X GET "https://api.roboflow.com/vision-events/use-cases" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

See the [Vision Events API Reference](https://docs.roboflow.com/developer/rest-api/vision-events) for the full response format.

### Manage Use Cases Programmatically

In addition to the dashboard, you can create, rename, archive, and unarchive Use Cases via the REST API. These endpoints require an API key with the `vision-events:manage` scope (unrestricted workspace API keys have access by default).

**Create a Use Case**

```bash
curl -X POST "https://api.roboflow.com/vision-events/use-cases" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "name": "assembly-line-qa" }'
```

**Rename a Use Case**

```bash
curl -X PUT "https://api.roboflow.com/vision-events/use-cases/USE_CASE_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "name": "assembly-line-qa-v2" }'
```

**Archive or Unarchive a Use Case**

```bash
curl -X POST "https://api.roboflow.com/vision-events/use-cases/USE_CASE_ID/archive" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST "https://api.roboflow.com/vision-events/use-cases/USE_CASE_ID/unarchive" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Archive a Use Case

Use Cases can be archived from the dashboard when they are no longer needed. Archived Use Cases and their events remain accessible but are hidden from the default view. Click **View archived use cases** at the bottom of the Use Cases table to see them.\ <br>

<figure><img src="https://662926385-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M6S9nPJhEX9FYH6clfW%2Fuploads%2F71mElYpzCyYcZ3Fupy3A%2FDashboard%20view%20for%20solution%20nine%20status.png?alt=media&#x26;token=46dd10e0-d93b-45c3-8c71-5cf4884e10d2" alt=""><figcaption></figcaption></figure>

### Custom Metadata Schema

After events are sent to a Use Case, the system infers a metadata schema based on the fields and value types observed. You can retrieve the inferred schema for a Use Case to understand what keys and value types are in use:

```bash
curl -X GET "https://api.roboflow.com/vision-events/custom-metadata-schema/assembly-line-qa" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Example response:**

```json
{
  "useCaseId": "assembly-line-qa",
  "fields": {
    "line_id": { "types": ["string"] },
    "shift": { "types": ["string"] },
    "temperature": { "types": ["number"] },
    "is_priority": { "types": ["boolean"] }
  }
}
```

See the [Vision Events API Reference](https://docs.roboflow.com/developer/rest-api/vision-events) for full details.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roboflow.com/deploy/vision-events/use-cases.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.