Use Cases

About

A Use Case groups Vision Events 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. This page explains when to use one Use Case versus several, and how to create and manage them.

Web App

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

Via the Agent

The Roboflow Agent creates Use Cases automatically when it builds a Workflow with Vision Events. It picks an existing Use Case if one fits, or creates a new one based on your described use case. You can also ask the Agent directly to set up a new 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

You can also create Use Cases via the REST API, see 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:

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

See the Vision Events API Reference 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

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

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

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>

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:

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

Example response:

{
  "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 for full details.

HTTP API

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

POST /vision-events/use-cases HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: application/json

{
  "name": "text"
}

curl -L \
  --request POST \
  --url 'https://api.roboflow.com/vision-events/use-cases' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "name": "text"
}'

const response = await fetch("https://api.roboflow.com/vision-events/use-cases", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    "name": "text"
  })
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.roboflow.com/vision-events/use-cases"
headers = {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
  "name": "text"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

{
  "id": "text",
  "name": "text"
}

{
  "error": "text"
}

{
  "error": "text"
}

Request Body Parameters

• name (string, required): A name for the use case. Must be between 1 and 256 characters. The name is trimmed of leading/trailing whitespace and must be unique within the workspace.

Example Request

curl -X POST "https://api.roboflow.com/vision-events/use-cases" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Manufacturing Line 1"
  }'

Example Response

{
  "id": "a1b3c8e1",
  "name": "Manufacturing Line 1"
}

{
  "error": "A solution with this name already exists"
}

{
  "error": "Insufficient permissions for this resource."
}

Notes

• New use cases are created with an active status by default.
• Use case names must be unique within a workspace. Attempting to create a use case with the same name as an existing one will return a 400 error.
• After creating a use case, you can reference its id as the useCaseId when creating vision events.

Update a Use Case

Update the name or status of an existing use case.

Required scope: vision-events:manage

PUT /vision-events/use-cases/{useCaseId} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: application/json

{
  "name": "text",
  "status": "active"
}

curl -L \
  --request PUT \
  --url 'https://api.roboflow.com/vision-events/use-cases/{useCaseId}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
  "name": "text",
  "status": "active"
}'

const response = await fetch("https://api.roboflow.com/vision-events/use-cases/{useCaseId}", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
  },
  body: JSON.stringify({
    "name": "text",
    "status": "active"
  })
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.roboflow.com/vision-events/use-cases/{useCaseId}"
headers = {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
  "name": "text",
  "status": "active"
}

response = requests.put(url, headers=headers, json=payload)
print(response.json())

{
  "id": "text",
  "name": "text"
}

{
  "error": "text"
}

{
  "error": "text"
}

{
  "error": "text"
}

Path Parameters

• useCaseId (string, required): The ID of the use case to update.

Request Body Parameters

At least one of the following fields must be provided:

• name (string, optional): A new name for the use case. Must be between 1 and 256 characters. Must be unique within the workspace.
• status (string, optional): The new status. One of active or inactive.

Example Request

curl -X PUT "https://api.roboflow.com/vision-events/use-cases/a1b3c8e1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Manufacturing Line 2"
  }'

Example Response

{
  "id": "a1b3c8e1",
  "name": "Manufacturing Line 2"
}

{
  "error": "A solution with this name already exists"
}

{
  "error": "Solution not found"
}

{
  "error": "Insufficient permissions for this resource."
}

List Use Cases

List all use cases that have recorded vision events in your workspace. To learn how to create and manage use cases, see the Use Cases documentation.

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

GET /vision-events/use-cases HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: application/json

curl -L \
  --request GET \
  --url 'https://api.roboflow.com/vision-events/use-cases' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Accept: application/json'

const response = await fetch("https://api.roboflow.com/vision-events/use-cases", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Accept": "application/json"
  }
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.roboflow.com/vision-events/use-cases"
headers = {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Accept": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

{
  "useCases": [
    {
      "id": "text",
      "name": "text",
      "status": "active",
      "workspaceId": "text",
      "createdAt": "text",
      "updatedAt": "text"
    }
  ],
  "lookbackDays": 1
}

{
  "error": "text"
}

Query Parameters

• status (string, optional): Filter by use case status. One of active or inactive. Defaults to active.

Example Request

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

Example Response

{
  "useCases": [
    {
      "id": "a1b3c8e1",
      "name": "Manufacturing Line 1",
      "status": "active",
      "workspaceId": "my-workspace",
      "createdAt": "2024-01-10T08:00:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "d4e5f6a7",
      "name": "Warehouse Inventory",
      "status": "active",
      "workspaceId": "my-workspace",
      "createdAt": "2024-01-12T14:00:00.000Z",
      "updatedAt": "2024-01-15T09:00:00.000Z"
    }
  ],
  "lookbackDays": 14
}

{
  "error": "Insufficient permissions for this resource."
}

Archive a Use Case

Archive a use case by setting its status to inactive. Archived use cases are hidden from listings by default and will reject new event ingestion.

Required scope: vision-events:manage

POST /vision-events/use-cases/{useCaseId}/archive HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: application/json

curl -L \
  --request POST \
  --url 'https://api.roboflow.com/vision-events/use-cases/{useCaseId}/archive' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Accept: application/json'

const response = await fetch("https://api.roboflow.com/vision-events/use-cases/{useCaseId}/archive", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Accept": "application/json"
  }
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.roboflow.com/vision-events/use-cases/{useCaseId}/archive"
headers = {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Accept": "application/json"
}

response = requests.post(url, headers=headers)
print(response.json())

{
  "success": true
}

{
  "error": "text"
}

{
  "error": "text"
}

Path Parameters

• useCaseId (string, required): The ID of the use case to archive.

Example Request

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

Example Response

{
  "success": true
}

{
  "error": "Solution not found"
}

{
  "error": "Insufficient permissions for this resource."
}

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 endpoint with status=inactive.
• You can restore an archived use case using the Unarchive a Use Case endpoint.

Unarchive a Use Case

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

Required scope: vision-events:manage

POST /vision-events/use-cases/{useCaseId}/unarchive HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: application/json

curl -L \
  --request POST \
  --url 'https://api.roboflow.com/vision-events/use-cases/{useCaseId}/unarchive' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Accept: application/json'

const response = await fetch("https://api.roboflow.com/vision-events/use-cases/{useCaseId}/unarchive", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Accept": "application/json"
  }
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.roboflow.com/vision-events/use-cases/{useCaseId}/unarchive"
headers = {
    "Authorization": "Bearer YOUR_SECRET_TOKEN",
    "Accept": "application/json"
}

response = requests.post(url, headers=headers)
print(response.json())

{
  "success": true
}

{
  "error": "text"
}

{
  "error": "text"
}

{
  "error": "text"
}

Path Parameters

• useCaseId (string, required): The ID of the use case to unarchive.

Example Request

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

Example Response

{
  "success": true
}

{
  "error": "Solution is not archived"
}

{
  "error": "Solution not found"
}

{
  "error": "Insufficient permissions for this resource."
}

Notes

• Only use cases with an inactive status can be unarchived. Attempting to unarchive an already active use case will return a 400 error.
• Once unarchived, the use case will appear in active listings and accept new event ingestion again.

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

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:

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

Create a Use Case

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

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

Archive a Use Case

ws.archive_vision_event_use_case("a1b3c8e1")

Unarchive a Use Case

ws.unarchive_vision_event_use_case("a1b3c8e1")

For more details on use case management, see the REST API reference.

MCP Server

Connect your AI agent to the MCP Server and it can manage use cases with these tools: