> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Observability API

The Observability API provides methods to retrieve traces, monitor application performance, score traces for evaluation, and record feedback linked to traces and spans.

## Getting a specific trace

Retrieve a specific trace by its ID, including all its spans and details:

```typescript
const trace = await mastraClient.getTrace('trace-id-123')
```

## Getting traces with filtering

Retrieve a paginated list of trace root spans with optional filtering:

```typescript
const traces = await mastraClient.getTraces({
  pagination: {
    page: 1,
    perPage: 20,
    dateRange: {
      start: new Date('2024-01-01'),
      end: new Date('2024-01-31'),
    },
  },
  filters: {
    name: 'weather-agent', // Filter by trace name
    spanType: 'agent', // Filter by span type
    entityId: 'weather-agent-id', // Filter by entity ID
    entityType: 'agent', // Filter by entity type
  },
})

console.log(`Found ${traces.spans.length} root spans`)
console.log(`Total pages: ${traces.pagination.totalPages}`)

// To get the complete trace with all spans, use getTrace
const completeTrace = await mastraClient.getTrace(traces.spans[0].traceId)
```

## Scoring traces

Score specific traces using registered scorers for evaluation:

```typescript
const result = await mastraClient.score({
  scorerName: 'answer-relevancy',
  targets: [
    { traceId: 'trace-1', spanId: 'span-1' }, // Score specific span
    { traceId: 'trace-2' }, // Score specific span which defaults to the parent span
  ],
})
```

## Getting scores by span

Retrieve scores for a specific span within a trace:

```typescript
const scores = await mastraClient.listScoresBySpan({
  traceId: 'trace-123',
  spanId: 'span-456',
  page: 1,
  perPage: 20,
})
```

## Feedback

Feedback methods create, list, and query human-in-the-loop signals such as ratings, thumbs, comments, and corrections. See the [feedback guide](https://mastra.ai/docs/observability/feedback) for examples and the [feedback reference](https://mastra.ai/reference/observability/feedback) for full schemas.

### Creating feedback

Create a feedback record linked to a trace or span:

```typescript
const response = await mastraClient.createFeedback({
  feedback: {
    traceId: 'trace-123',
    spanId: 'span-456',
    feedbackSource: 'user',
    feedbackType: 'rating',
    value: 1,
    comment: 'Helpful answer.',
  },
})
```

### Listing feedback

Retrieve paginated feedback records with optional filters:

```typescript
const feedback = await mastraClient.listFeedback({
  filters: {
    feedbackType: 'rating',
    feedbackSource: 'studio',
  },
  pagination: { page: 0, perPage: 20 },
  orderBy: { field: 'timestamp', direction: 'DESC' },
})
```

### Aggregating feedback

Aggregate numeric feedback values, such as ratings or thumbs encoded as `1` and `-1`:

```typescript
const averageRating = await mastraClient.getFeedbackAggregate({
  feedbackType: 'rating',
  aggregation: 'avg',
  comparePeriod: 'previous_day',
})
```

### Grouping feedback

Group numeric feedback by observability dimensions:

```typescript
const ratingsByAgent = await mastraClient.getFeedbackBreakdown({
  feedbackType: 'rating',
  groupBy: ['entityName'],
  aggregation: 'avg',
})
```

### Querying feedback over time

Bucket numeric feedback by interval:

```typescript
const ratingsOverTime = await mastraClient.getFeedbackTimeSeries({
  feedbackType: 'rating',
  interval: '1h',
  aggregation: 'avg',
  groupBy: ['feedbackSource'],
})
```

### Querying feedback percentiles

Return percentile series for numeric feedback values:

```typescript
const ratingPercentiles = await mastraClient.getFeedbackPercentiles({
  feedbackType: 'rating',
  percentiles: [0.5, 0.95],
  interval: '1d',
})
```

## Related

- [Feedback guide](https://mastra.ai/docs/observability/feedback): Learn how to create, list, and query feedback
- [Feedback reference](https://mastra.ai/reference/observability/feedback): Review feedback schemas and HTTP routes
- [Agents API](https://mastra.ai/reference/client-js/agents): Learn about agent interactions that generate traces
- [Workflows API](https://mastra.ai/reference/client-js/workflows): Understand workflow execution monitoring