# Outcomes Tracking

Track and measure the business value of your AI workflows. The Outcomes Dashboard connects complete AI execution costs to real business results—revenue generated, conversions achieved, and cost savings across your AI operations.

**Access:** Main navigation → Outcomes

***

## Overview

The Outcomes Dashboard answers critical questions about your AI investments:

* **Which jobs deliver value?** Compare outcomes across job types
* **What's my AI ROI by job type?** See return on investment per job
* **Where should I optimize?** Identify high-cost, low-value jobs

The dashboard connects technical metrics (tokens, latency, errors) to business results (revenue, conversions, cost savings)—giving you the complete picture of AI impact.

***

## Key Concepts

### Job Executions

A **job execution** represents a single run of an AI agent workflow—a complete unit of work with a clear business purpose. Examples:

* Processing a customer support ticket from start to resolution
* Qualifying and routing a sales lead through your pipeline
* Reviewing code and providing feedback
* Analyzing data and producing insights

Each execution consists of one or more AI transactions (model calls, embeddings, tool invocations) working together to accomplish a goal. These transactions can occur across one trace or many traces. The Outcomes feature introduces a higher level aggregation (an agentic Job) that sits above both individual AI transactions as well as traces that include numerous AI transactions.

### Outcome Types

Report the business result of each job:

* **CONVERTED** - Achieved the business goal (sale, signup, resolution)
* **ESCALATED** - Required human escalation
* **DEFLECTED** - Successfully handled without human intervention (cost savings)
* **UNSUCCESSFUL** - Did not achieve the business goal and was not escalated
* **CUSTOM** - Custom outcome defined by your organization
* **PENDING** - No outcome reported yet (default state)

### Execution Status

Track technical completion status – success or failure of the individual AI transctions making up the job. you can think about this status as the engineering view of the world. Did the individual AI transactions complete successfully or encounter errors? this is distinct from the business outcome of the job reported separately. For example, it is possible for every AI transaction to succeed, but the business outcome of converting the sale not to be completed.

* **SUCCESS** - Job executed without errors
* **FAILED** - Encountered a technical failure
* **CANCELLED** - Cancelled before completion

### ROI Calculation

```
ROI = ((Outcome Value - Total Cost) / Total Cost) × 100
```

**Example:**

* AI Cost: $2.50
* Outcome Value: $500 (converted sale)
* ROI: (($500 - $2.50) / $2.50) × 100 = **19,900%**

**Note:** ROI displays as `null` when total cost is $0 or no outcome has been reported.

***

## Getting Started

### 1. Track Jobs via Telemetry

Include job tracking fields when sending AI metrics to Revenium.

```json
{
  "agenticJobId": "support-ticket-12345",
  "agenticJobType": "support-ticket",
  "agenticJobName": "Handle Support Ticket #12345",
  "agenticJobVersion": "1.0.0",
  "model": "gpt-4",
  "provider": "OpenAI",
  "totalCost": 0.05
}
```

**Required:**

* `agenticJobId` (String, max 256 chars) - Unique identifier for this job execution

**Recommended:**

* `agenticJobType` (String, max 128 chars) - Job category (normalized to lowercase)
* `agenticJobName` (String, max 512 chars) - Human-readable display name
* `agenticJobVersion` (String, max 64 chars) - Version for tracking job evolution

**What happens automatically:**

* Revenium creates a job entity when it receives a new `agenticJobId`
* All transactions with the same `agenticJobId` are grouped under a job for that outcome
* Costs, tokens, and transaction counts accumulate automatically
* These appear in the dashboard immediately

### 2. Report Outcomes

After your job completes, report the business outcome:

```bash
curl -X POST "https://api.revenium.io/v2/api/jobs/{jobId}/outcome?teamId={yourTeamId}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "executionStatus": "SUCCESS",
    "outcomeType": "CONVERTED",
    "outcomeValue": 500.00,
    "metadata": "{\"customerId\": \"123\", \"notes\": \"Upgraded to premium\"}"
  }'
```

**Required:**

* `executionStatus` - `SUCCESS`, `FAILED`, or `CANCELLED`

**Optional:**

* `outcomeType` - `CONVERTED`, `ESCALATED`, `DEFLECTED`, `UNSUCCESSFUL`, or `CUSTOM`
* `outcomeValue` - Monetary value
* `metadata` - JSON string with additional context

**Important:** Outcomes are **immutable** once reported. This ensures historical data remains accurate.

**Alternative:** Report outcomes via UI:

1. Navigate to Outcomes Dashboard → All Outcomes tab
2. Click on a given job to view details
3. Click "Report Outcome" button
4. Fill in the form and submit

### 3. View Metrics

**Overview Tab:**

* Key metric cards (Total ROI, Total Cost, Total Value, Job Count)
* Revenue vs Cost trends over time
* Conversion funnel (Total Jobs → Successful → Converted)
* Value composition (Revenue vs Cost Savings)
* Outcome trends by job type
* Job type comparison table
* Top jobs by value

**All Jobs Tab:**

* Searchable, filterable jobs table
* Filters: Job ID & Type, Execution Status, Outcome Type, Date Range
* Click any job to see transaction timeline and details

***

## Dashboard Features

### Overview Tab

![Outcomes Overview Page](https://2470865788-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSUfCzMW8qWeXstipFXEh%2Fuploads%2Fgit-blob-00599f579861eee1b5eb006defa984f6404102df%2FOutcomesOverviewPage.jpg?alt=media)

The Overview tab provides a comprehensive view of your AI workflow outcomes with value composition, conversion funnels, and ROI analysis.

#### Metric Cards

Four key metrics:

* **Total ROI** - Aggregated ROI across all jobs with trend indicator
* **Total Cost** - Total AI spending for the selected period
* **Total Value** - Sum of all outcome values reported
* **Job Count** - Number of jobs executed

Each card shows current value and trend vs previous period with color-coded indicators:

* **Total ROI, Total Value, Job Count**: ↑ green (better), ↓ red (worse)
* **Total Cost**: ↑ red (worse), ↓ green (better)

#### Revenue vs Cost Chart

Time series visualization showing:

* Revenue (outcome value) as bars
* Cost as line overlay
* ROI percentage trend
* Hover for exact values at any point

#### Conversion Funnel

Three-stage funnel visualization:

1. **Total Jobs** - All workflows in period
2. **Successful Jobs** - the AI task execution for the individual span completed without error
3. **Converted Jobs** - the desired business outcome was achieved

Shows success rate and conversion rate percentages.

#### Value Composition

Visual breakdown of business value across two outcome types:

* **Revenue** - Conversion value
* **Cost Savings** - Deflection value

#### Job Type Table

Aggregated metrics by Job type:

**Columns:**

* **Job Type** - Category
* **Job Count** - Number executed
* **Total Cost** - Aggregate spending
* **Total Value** - Aggregate outcome value
* **Average ROI** - Mean ROI for this type
* **Success Rate** - % completed successfully
* **Conversion Rate** - % that converted

Click any column header to sort and identify best/worst performing types.

#### Top Jobs Table

Highest-value individual jobs with details:

* Job Name/ID (clickable)
* Type badge
* Outcome value
* Total cost
* ROI
* Execution timestamp

### All Jobs Tab

![All Jobs Page](https://2470865788-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSUfCzMW8qWeXstipFXEh%2Fuploads%2Fgit-blob-d4fc9780fdd49d842166910b9ae29d01ef574596%2FAllJobsPage.jpg?alt=media)

Complete list of all agentic workflow execution instances. Click on any row to view detailed job information, costs, and transaction history.

Jobs list with:

**Filters:**

* Job Type dropdown
* Execution Status (SUCCESS, FAILED, CANCELLED)
* Outcome Type (CONVERTED, ESCALATED, DEFLECTED, UNSUCCESSFUL, CUSTOM, PENDING)
* Date Range (Last 7 days, 30 days, or custom)

**Table Features:**

* Sortable columns
* Search by name/ID
* Pagination (20 per page)
* Export to CSV

### Job Detail View

![Job Detail View](https://2470865788-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSUfCzMW8qWeXstipFXEh%2Fuploads%2Fgit-blob-dd5c794bdb925835ac9d93ca09403416218df631%2FJobsDetailedView.jpg?alt=media)

Click any job to see comprehensive execution details, metrics, and transaction timeline.

#### Details Card

* Job ID, Name, Type, Version
* Created and Updated timestamps
* Execution Status and Outcome Type

#### Metrics Cards

* **Total Cost** - With token breakdown
* **Outcome Value** - Monetary value
* **ROI** - Calculated percentage
* **Transactions** - Count of AI operations

#### Value Analysis Card

Visual breakdown showing:

* Cost components (token vs tool)
* Outcome value
* Calculated ROI with explanation

#### Transaction Timeline

Waterfall visualization of all AI transactions:

* Horizontal bars representing each transaction
* Bar width = duration
* Bar color = cost intensity
* X-axis = time (relative to job start)

**Hover tooltips show:**

* Transaction ID, Agent, Model, Provider
* Duration, Cost, Tokens
* Status

**Transaction Details Table**

Below the waterfall:

* Timestamp, Model, Provider
* Duration, Tokens (input/output/cached)
* Cost, Status
* Click any row for full transaction details

***

## Use Cases

### Support Ticket Deflection

Track cost savings from AI-powered support automation:

**Track Job:**

```javascript
await sendAIMetric({
  agenticJobId: `support-ticket-${ticketId}`,
  agenticJobType: "support-ticket",
  agenticJobName: `Handle Ticket ${ticketId}`,
  totalCost: 0.02
})
```

**Report outcome:**

```javascript
const wasDeflected = !ticket.escalatedToHuman

// Get Revenium job ID
const jobsResponse = await fetch(
  `https://api.revenium.io/v2/api/jobs?teamId=${YOUR_TEAM_ID}&type=support-ticket`,
  { headers: { "Authorization": `Bearer ${YOUR_TOKEN}` } }
)
const jobs = await jobsResponse.json()
const job = jobs._embedded.jobResourceList.find(j => j.agenticJobId === agenticJobId)

// Report outcome
await reportJobOutcome({
  jobId: job.id,
  teamId: YOUR_TEAM_ID,
  executionStatus: "SUCCESS",
  outcomeType: wasDeflected ? "DEFLECTED" : "ESCALATED",
  outcomeValue: wasDeflected ? 50.00 : 0 // $50 = human agent time
})
```

**Example results:**

* Deflection rate: 60-80%
* Cost per deflected ticket: $0.05-0.15 (AI) vs $50 (human)
* ROI: 30,000%+ for deflected tickets

### Sales Lead Qualification

Measure conversion value and optimize qualification:

**Track Job:**

```javascript
await sendAIMetric({
  agenticJobId: `sales-lead-${leadId}`,
  agenticJobType: "sales-lead",
  totalCost: 0.05
})
```

**Report outcome when lead converts:**

```javascript
// Get Revenium job ID
const jobsResponse = await fetch(
  `https://api.revenium.io/v2/api/jobs?teamId=${YOUR_TEAM_ID}`,
  { headers: { "Authorization": `Bearer ${YOUR_TOKEN}` } }
)
const jobs = await jobsResponse.json()
const job = jobs._embedded.jobResourceList.find(j => j.agenticJobId === agenticJobId)

// Report conversion
await reportJobOutcome({
  jobId: job.id,
  teamId: YOUR_TEAM_ID,
  executionStatus: "SUCCESS",
  outcomeType: "CONVERTED",
  outcomeValue: deal.contractValue
})
```

**Example results:**

* Conversion rate: 10-30%
* AI cost per lead: $0.10-1.50
* Revenue per converted lead: varies
* ROI: based on revenue converted / cost per lead

***

## Best Practices

### Agentic Job ID Naming

Use meaningful IDs that map to real-world entities:

**Good:**

```javascript
`support-ticket-${ticketId}`
`order-${orderId}-fraud-check`
`pr-${repoName}-${prNumber}-review`
`user-${userId}-onboarding-${date}`
```

**Bad:**

```javascript
`job-1`, `job-2` // Too generic
`a3d5e2f1-4b2c-...` // Random UUID without context
`daily-batch-job` // Too broad
`${transactionId}` // Too granular
```

### Value Calculation Strategy

Be consistent in how you value outcomes:

| Job Type               | Value Strategy                                                                                                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Support Tickets**    | Average human agent cost per ticket for deflected; for escalated, keep full value and [track human cost via tool metering](#handling-escalated-outcomes-and-human-costs) |
| **Sales Leads**        | Actual contract value for conversions, or average deal size as proxy                                                                                                     |
| **Code Reviews**       | Developer time saved ($100-200/hour)                                                                                                                                     |
| **Content Generation** | Attributed revenue from campaigns, or freelancer cost savings                                                                                                            |

**Tips:**

* Use conservative estimates
* Document your methodology
* Be consistent across similar job types
* Update values periodically based on actual data

### Always Report Outcomes

Report outcomes for **all** jobs, not just successful ones:

**Why:**

* Track true success rate
* Measure autonomy rate (% handled without escalation)
* Calculate accurate cost per successful outcome
* Identify failure patterns

**Failed Jobs:**

```javascript
await reportJobOutcome({
  executionStatus: "FAILED",
  // Omit outcomeType and outcomeValue
  metadata: JSON.stringify({ error: errorMessage })
})
```

**Escalated Jobs:**

```javascript
await reportJobOutcome({
  executionStatus: "SUCCESS",
  outcomeType: "ESCALATED",
  outcomeValue: fullBusinessValue, // Keep full value — track human cost separately
  metadata: JSON.stringify({ escalationReason: reason })
})
```

{% hint style="warning" %}
**Don't discount `outcomeValue` to account for human involvement.** Instead, meter the human effort as a tool cost. See [Handling Escalated Outcomes and Human Costs](#handling-escalated-outcomes-and-human-costs) below.
{% endhint %}

### Job Type Naming

Use consistent, descriptive names:

**Guidelines:**

* Lowercase with hyphens: `support-ticket`
* Specific, not generic: `loan-application-review` not just `review`
* Action-oriented: `lead-qualification` not `leads`

**Good examples:**

```
customer-support-chat
sales-lead-qualification
code-review-security
content-blog-generation
fraud-detection-realtime
```

**Bad examples:**

```
chat          // Too generic
job-1    // Not descriptive
CUSTOMER_SUPPORT  // Wrong format
```

### Handling Escalated Outcomes and Human Costs

ROI has two levers—**value** and **cost**—and each should reflect reality independently. A common mistake is discounting the `outcomeValue` for ESCALATED jobs to account for human involvement. This hides the true cost structure and produces misleading ROI.

**The correct approach:**

1. **Keep `outcomeValue` at full value** — the business result was still delivered, even if a human helped complete it
2. **Track human intervention cost via tool metering** — register a tool (e.g., `engineering-time`) in the [Tool Registry](https://docs.revenium.io/tool-registry) and meter the human effort as a tool cost
3. **Let the ROI formula do the work** — `ROI = ((value - totalCost) / totalCost) × 100` naturally decreases as `totalCost` increases from tool costs

{% hint style="info" %}
**Outcomes control value. Tool metering controls cost.** Both are needed for ESCALATED jobs to produce accurate ROI.
{% endhint %}

**Example: Why discounting value is wrong**

A support job is escalated to a human agent. The AI handled initial triage (token cost: $0.50), and a human spent 45 minutes resolving it at $75/hour ($56.25).

| Approach                           | Outcome Value | Token Cost | Tool Cost | Total Cost | ROI     |
| ---------------------------------- | ------------- | ---------- | --------- | ---------- | ------- |
| ❌ **Wrong:** Discount value to 50% | $143.00       | $0.50      | —         | $0.50      | 28,500% |
| ✅ **Correct:** Meter human cost    | $286.00       | $0.50      | $56.25    | $56.75     | 404%    |

The wrong approach inflates ROI by hiding the human cost—the $56.25 in human time is invisible. The correct approach shows the true economics: the job still delivered full value, but it cost $56.75 to produce, not $0.50.

**How to meter human intervention time:**

1. **Register a tool** in the [Tool Registry](https://docs.revenium.io/tool-registry) for human effort:
   * **Tool ID**: `engineering-time`
   * **Tool Type**: Custom
   * **Unit Price**: $75.00 per hour (or your organization's loaded rate)
2. **Meter usage** when the escalation completes:

```json
POST /v2/tool/events
{
  "toolId": "engineering-time",
  "operation": "manual-review",
  "durationMs": 2700000,
  "success": true,
  "timestamp": "2025-01-15T14:30:00Z",
  "traceId": "trace-for-this-job",
  "usageMetadata": {
    "reviewer": "jane.doe@company.com",
    "agenticJobId": "support-ticket-12345"
  }
}
```

The tool cost is automatically attributed to the job and included in the ROI calculation. No changes to the outcome reporting are needed—the ROI formula accounts for all costs.

See [Tool Registry → Human Time Allocation](https://docs.revenium.io/tool-registry) for full setup details.

***

## API Reference

Base URL: `https://api.revenium.io/v2/api`

All endpoints require:

* `Authorization: Bearer YOUR_TOKEN` header
* `teamId` query parameter

Full API Documentation: <https://revenium.readme.io>

### List Jobs

**`GET /jobs`**

Retrieve paginated list of jobs and their outcomes with optional filters.

**Query Parameters:**

* `teamId` (required) - Your organization ID
* `type` - Filter by job type
* `executionStatus` - SUCCESS, FAILED, CANCELLED
* `outcomeType` - CONVERTED, ESCALATED, DEFLECTED, UNSUCCESSFUL, CUSTOM, PENDING
* `startDate`, `endDate` - ISO 8601 dates
* `page` - Page number (default: 0)
* `size` - Page size (default: 20, max: 100)
* `sort` - Sort field and direction (default: `created,DESC`)

### Get Job Details

**`GET /jobs/{jobId}?teamId={yourTeamId}`**

Retrieve details for a specific job.

### Report Job Outcome

**`POST /jobs/{jobId}/outcome?teamId={yourTeamId}`**

Report execution status and business outcome.

**Request Body:**

```json
{
  "executionStatus": "SUCCESS",
  "outcomeType": "CONVERTED",
  "outcomeValue": 500.00,
  "metadata": "{\"notes\": \"Customer upgraded\"}"
}
```

**Response Codes:**

* `200 OK` - Outcome reported successfully
* `409 Conflict` - Outcome already reported (immutable)
* `404 Not Found` - Job not found

### Get Job ROI

**`GET /jobs/{jobId}/roi?teamId={yourTeamId}`**

Retrieve aggregated ROI metrics for a specific job.

### Get Job Transactions

**`GET /jobs/{jobId}/transactions?teamId={yourTeamId}`**

Retrieve all AI transactions for waterfall visualization.

### Get Job Types

**`GET /jobs/types?teamId={yourTeamId}`**

List all distinct job types in your organization.

### Get Conversion Funnel

**`GET /jobs/conversion-funnel?teamId={yourTeamId}`**

Retrieve conversion funnel metrics with optional filters:

* `startDate`, `endDate` - ISO 8601 dates
* `jobType` - Filter by specific type

***

## Related Documentation

* [Tool Registry](https://docs.revenium.io/tool-registry) — Track costs beyond tokens, including human-in-the-loop time for escalated workflows
* [AI Metrics Overview](https://docs.revenium.io/ai-metrics)
* [Trace Analytics](https://docs.revenium.io/trace-analytics)
* [Cost Analytics](https://docs.revenium.io/cost-analytics)