Complete observability for every AI request

What are Request Logs?

Request Logs are ModelRiver's comprehensive audit trail for every AI request made through your API. Each log entry captures the complete lifecycle of a request, from initial provider attempts through successful responses or failures, including webhook deliveries and backend callbacks.

Why Request Logs exist

Request Logs serve multiple critical purposes:

• Debugging production issues – Inspect exact request/response payloads to identify why a request failed or returned unexpected results
• Cost analysis and optimization – Track token usage and pricing per request to understand spending patterns and optimize model selection
• Performance monitoring – Monitor request latency, identify slow providers, and track performance trends over time
• Provider reliability tracking – See which providers fail most often, how often fallbacks trigger, and make data-driven decisions about provider selection
• Billing reconciliation – Match API usage to invoices and verify pricing accuracy
• Compliance and audit trails – Maintain complete records of AI interactions for regulatory compliance or internal audits
• Testing and validation – Review test mode and playground requests separately from production to validate workflows before deployment

Where to find Request Logs

Navigate to Request Logs in your project console using the clipboard sheet icon in the sidebar. The logs view shows all requests for your active project, with powerful filtering options to focus on specific request types.

Request Log List View

The Request Logs list provides a high-level overview of all requests in your project, with essential information visible at a glance.

Table columns

Filtering options

The filter dropdown lets you focus on specific request types, essential for separating production traffic from testing and debugging:

• All requests – Every request in the project, regardless of source

  • Use when: You want a complete overview or are searching broadly

• Live mode – Production API requests (seed_batch is null)

  • Use when: Debugging production issues, analyzing real user traffic, or monitoring live system health
  • Why: These are actual API calls from your applications, not test runs

• Test mode – Workflow test mode requests (seed_batch starts with "test_mode:")

  • Use when: Reviewing integration tests, CI/CD pipeline runs, or development environment requests
  • Why: Test mode requests use sample data from structured outputs, so they don't consume provider credits but still create logs for validation

• Playground (Production) – Console testing with production workflows (seed_batch starts with "pg:")

  • Use when: Reviewing ad-hoc tests you ran in the console using production workflows
  • Why: These are real provider calls made from the console, useful for validating workflow changes before deploying

• Playground (Test mode) – Console testing with test mode workflows (seed_batch starts with "pg_test_mode:")

  • Use when: Reviewing console tests that used test mode workflows
  • Why: These don't consume credits but help validate workflow logic

• All Playground – Both playground types combined

  • Use when: Reviewing all console testing activity regardless of workflow mode

Why filtering matters: Separating production from testing prevents test noise from obscuring real issues. Filtering by seed_batch patterns ensures you're analyzing the right requests for your current task.

Additional features

• Refresh button – Manually reload the latest logs without navigating away

  • Why: Useful when monitoring real-time issues or after making API calls

• Pagination and "See more" – Load additional pages of logs incrementally

  • Why: Efficiently browse large log volumes without loading everything at once

• Status indicators – Color-coded badges (green for success, red for error)

  • Why: Instant visual feedback on request health

• Provider icons – Visual provider logos next to provider names

  • Why: Faster recognition of which vendors are being used

• Failed models badge – Shows count of failed provider attempts before success

  • Why: Quickly identify requests that required fallbacks, indicating provider instability

• Event badge – Indicates event-driven workflow requests

  • Why: Distinguish async event-driven requests from standard sync requests

• Click to view details – Click any row to open the detailed log view

  • Why: Access complete request lifecycle information

Request Log Detail View

Click any log entry to open the detail view, which provides comprehensive information about a single request's complete lifecycle.

Accessing the detail view

1. Navigate to Request Logs in your project
2. Click any row in the logs table
3. The detail view opens, showing the timeline and detailed information

Timeline view (always visible)

The timeline is the centerpiece of the detail view, providing a visual representation of the complete request lifecycle. It's always visible at the top of the detail page, even when viewing specific timeline item details.

Why the timeline exists: The timeline shows the complete story of a request—not just the final result, but every attempt, webhook delivery, and callback. This is essential for understanding:

• Why a request took longer than expected (multiple provider attempts)
• Whether webhooks were delivered successfully
• If backend callbacks completed for event-driven workflows
• The complete failover chain when providers fail

Timeline components

The timeline displays items in chronological order, showing the complete request journey:

1. Failover Attempts

Failed provider/model attempts that occurred before the successful request.

• Visual indicator: Amber/yellow status badge with provider icon

• Shows: Provider name, model name, duration, timestamp, and failure reason

• Why it exists: When ModelRiver's fallback system kicks in, you see exactly which providers failed and why. This helps you:

  • Identify unreliable providers
  • Understand why fallbacks triggered
  • Debug provider-specific issues
  • Make informed decisions about provider selection

• Click to view: Request body, response body, and error details for the failed attempt

2. Main Request

The successful or final request that returned the response to your application.

• Visual indicator: Green status badge (success) or red status badge (error) with provider icon

• Shows: Provider name, model name, duration, token usage, timestamp

• Why it exists: This is the request that actually served your application. It shows:

  • Which provider/model ultimately handled the request
  • Performance metrics (duration, tokens)
  • The actual request/response payloads

• Click to view: Complete request body, response body, and metadata

3. Webhook Deliveries

Webhook notifications sent for async requests or event-driven workflows.

• Visual indicator: Status badges showing delivery state:

  • Planned (gray) – Webhook is queued but not yet sent
  • Delivering (blue) – Webhook delivery is in progress
  • Success (green) – Webhook was delivered successfully
  • Error (red) – Webhook delivery failed

• Shows: Webhook URL, delivery time, duration, HTTP status code, error messages

• Why it exists: For async requests, webhooks are how your backend receives notifications. The timeline shows:

  • Whether webhooks were sent
  • Delivery success/failure
  • How long delivery took
  • Retry attempts (if any)

• Click to view: Webhook payload, response from your endpoint, retry button (when applicable)

4. Backend Callbacks

Callback responses from your backend for event-driven workflows.

• Visual indicator: Lightning bolt icon with "Backend Callback" label

• Shows: Callback status (Success/Timeout), timestamp, simulated indicator (for playground tests)

• Why it exists: For event-driven workflows, your backend processes the AI response and calls back to ModelRiver. The timeline shows:

  • Whether your callback was received
  • If the callback completed successfully or timed out
  • When the callback occurred

• Click to view: Callback payload (webhook payload sent to your backend), callback response (data your backend sent back)

Why the timeline order matters: The chronological order tells the complete story. Failover attempts show resilience, the main request shows the final result, webhook deliveries show async notifications, and callbacks show backend processing. This sequence helps you understand the full request lifecycle.

Detail View Features

When you click a timeline item, the detail view expands to show comprehensive information about that specific component.

Provider Request Details

When viewing a provider request (main request or failover attempt), you see:

Header information

• Provider icon and name – Visual identification of the AI provider
• Model name – Specific model used (e.g., gpt-4o-mini, claude-3-5-sonnet-20241022)
• Status – Success, Failed, or Error with color-coded badge
• Duration – Request latency in milliseconds
• Timestamp – When the request occurred (relative time, e.g., "5m ago")

Request Body tab

The Request Body tab shows exactly what was sent to the AI provider.

• Raw JSON view – Complete JSON payload in formatted, syntax-highlighted code editor

  • Why: See the exact structure and content sent to the provider
  • Use when: Debugging why a request failed, verifying prompt content, or understanding request formatting

• Preview (tree view) – Interactive JSON tree viewer for easier navigation

  • Why: Explore large payloads more easily, collapse/expand sections, and focus on specific fields
  • Use when: Inspecting complex nested structures or large message arrays

• Copy functionality – One-click copy of the entire request body

  • Why: Quickly share request details with team members or use in API testing tools

Why request body inspection matters: Understanding what was sent helps you:

• Debug prompt engineering issues
• Verify workflow configuration is correct
• Identify data quality problems
• Reproduce issues in testing environments

Response Body tab

The Response Body tab shows the complete response from the AI provider.

• Raw JSON view – Full provider response in formatted code editor

  • Why: See exactly what the provider returned, including all metadata
  • Use when: Analyzing response quality, debugging parsing issues, or verifying structured output compliance

• Preview (tree view) – Interactive JSON tree for response exploration

  • Why: Navigate large responses, focus on specific fields, and understand response structure
  • Use when: Inspecting complex structured outputs or large text completions

• Copy functionality – Copy the entire response for analysis or sharing

Why response body inspection matters: The response body shows:

• The actual AI-generated content
• Token usage breakdown
• Provider-specific metadata
• Structured output compliance
• Error messages (if the request failed)

Webhook Delivery Details

When viewing a webhook delivery, you see comprehensive delivery information:

Status information

• Status badges:

  • Planned – Webhook is queued, waiting to be sent
  • Delivering – Webhook HTTP request is in progress
  • Success – Webhook was delivered successfully (2xx response)
  • Error – Webhook delivery failed (non-2xx response, timeout, or network error)

• Callback status (for event-driven workflows) – Shows if your backend callback was received:

  • Progress – Callback is expected but not yet received
  • Success – Callback was received successfully
  • Error – Callback indicated an error or wasn't received within timeout

• Retry button (when applicable) – Manually retry a failed webhook delivery

  • Available when: can_retry is true and the delivery failed
  • Limitations: See Webhook Retry Logic for detailed rules

Delivery metadata

• Webhook URL – The endpoint that received (or should receive) the webhook
• Delivery time – When the webhook was sent (relative time)
• Duration – How long the HTTP request took (if available)
• HTTP status code – Response code from your endpoint (if available)
• Error message – Detailed error if delivery failed

Request Data tab (webhook payload)

Shows the exact payload sent to your webhook endpoint.

• Raw JSON view – Complete webhook payload
• Preview (tree view) – Interactive JSON tree
• Copy functionality – Copy payload for testing or debugging

Why webhook payload inspection matters: Understanding the payload helps you:

• Verify your webhook handler receives expected data
• Debug webhook processing issues
• Test webhook endpoints with real payloads
• Understand event-driven workflow data structure

Response tab (webhook response)

Shows the response from your webhook endpoint.

• Raw view – Complete HTTP response body
• Preview (tree view) – If response is JSON
• Copy functionality – Copy response for analysis

Why webhook response inspection matters: Your endpoint's response shows:

• Whether your handler processed the webhook correctly
• Any errors or validation issues
• Response timing (affects delivery duration)

Backend Callback Details

For event-driven workflows, callback details show:

• Callback payload – The webhook payload your backend received (same as Request Data tab for the webhook)
• Callback response – The data your backend sent back to ModelRiver via the callback URL
• Status – Success (callback received) or Timeout (callback not received within 5 minutes)
• Simulated indicator – For playground tests, shows that the callback was simulated

Why callback details matter: Understanding callbacks helps you:

• Verify your backend processed the AI response correctly
• Debug callback failures or timeouts
• Understand the data flow in event-driven workflows

Key Fields Explained

Request Logs capture extensive metadata about each request. Understanding these fields helps you make the most of the logging system.

Provider & Model

What it is: The AI provider (OpenAI, Anthropic, Google, etc.) and specific model (e.g., gpt-4o, claude-3-5-sonnet-20241022) used for the request.

Why it exists:

• Cost attribution – Different models have different pricing; track which models drive costs
• Performance comparison – Compare latency and quality across providers/models
• Usage patterns – Understand which providers/models your application uses most
• Provider reliability – Identify which providers fail most often

How to use it: Filter logs by provider to analyze vendor-specific issues, or compare model performance by reviewing duration and success rates.

Token Usage

What it is: Three metrics tracking AI consumption:

• Prompt tokens (input tokens) – Tokens in the request sent to the provider
• Completion tokens (output tokens) – Tokens in the response generated by the provider
• Total tokens – Sum of prompt and completion tokens

Why it exists:

• Cost calculation – Most providers charge per token; input and output tokens often have different rates
• Usage monitoring – Track token consumption trends to predict costs
• Optimization – Identify requests with unexpectedly high token usage
• Billing reconciliation – Match token counts to provider invoices

How to use it: Review token usage to identify expensive requests, optimize prompts to reduce input tokens, or set usage alerts based on token thresholds.

Duration

What it is: Request latency in milliseconds, measured from when the request is sent to the provider until the response is received.

Why it exists:

• Performance monitoring – Track request speed and identify slow requests
• SLA tracking – Ensure requests complete within acceptable timeframes
• Provider comparison – Compare latency across different providers/models
• Optimization – Identify performance bottlenecks and optimize workflows

How to use it: Monitor duration trends to spot performance degradation, compare providers to choose faster options, or set alerts for requests exceeding thresholds.

Status

What it is: The final state of the request: success (completed successfully) or error (failed).

Why it exists:

• Health monitoring – Quickly identify failing requests
• Error tracking – Understand failure rates and patterns
• Alerting – Trigger alerts when error rates exceed thresholds
• Debugging – Filter to errors to focus on issues

How to use it: Use status filters to focus on errors, monitor success rates over time, or set up alerts for error spikes.

Seed Batch

What it is: An identifier that categorizes requests by source. Values include:

• null – Live production requests from your API
• "test_mode:{channel_id}" – Test mode workflow requests
• "pg:{channel_id}" – Playground requests with production workflows
• "pg_test_mode:{channel_id}" – Playground requests with test mode workflows
• "callback:{channel_id}" or "pg_callback:{channel_id}" – Backend callback logs

Why it exists:

• Environment separation – Distinguish production from testing traffic
• Filtering – Enable powerful filtering to focus on specific request types
• Analytics – Analyze production vs. test usage separately
• Debugging – Isolate issues to specific environments

How to use it: Use seed batch patterns to filter logs (see Filtering & Organization), or analyze test vs. production usage patterns separately.

Primary Request ID

What it is: A UUID linking failed provider attempts to the successful request that ultimately served the response.

Why it exists:

• Failover tracking – See the complete chain of provider attempts for a single logical request
• Resilience analysis – Understand how often fallbacks trigger and which providers fail
• Debugging – Trace why a request required multiple attempts
• Cost attribution – Understand the true cost of a request including failed attempts

How to use it: When viewing a failed model attempt, the primary request ID links to the successful request. This helps you understand the complete failover chain and identify unreliable providers.

Event Name

What it is: A custom identifier for event-driven workflows. Set when creating a workflow with an event name.

Why it exists:

• Event-driven workflow identification – Distinguish event-driven requests from standard requests
• Filtering – Filter logs to specific event types
• Workflow tracking – Track usage of specific event-driven workflows
• Debugging – Isolate issues to specific event types

How to use it: Filter logs by event name to analyze specific event-driven workflows, or use event names to track workflow usage patterns.

Channel ID

What it is: A unique identifier for async requests, linking the initial request, webhook deliveries, and callbacks together.

Why it exists:

• Async request tracking – Link all components of an async request lifecycle
• Webhook correlation – Match webhook deliveries to their originating requests
• Callback correlation – Link backend callbacks to their webhook deliveries
• Debugging – Trace the complete async request flow

How to use it: Use channel ID to find all related logs for an async request, including webhook deliveries and callbacks. This is essential for debugging event-driven workflows.

Is Async

What it is: A boolean flag indicating whether the request was synchronous (false) or asynchronous (true).

Why it exists:

• Request type distinction – Understand which requests are sync vs. async
• Logging pattern differences – Sync and async requests may have different logging behaviors
• Analytics – Analyze sync vs. async usage patterns
• Debugging – Understand request flow based on type

How to use it: Filter or analyze logs based on sync vs. async to understand usage patterns or debug type-specific issues.

Price

What it is: The cost per request in your account currency, calculated based on token usage and provider pricing.

Why it exists:

• Cost tracking – Understand the actual cost of each request
• Billing reconciliation – Match logs to invoices
• Cost optimization – Identify expensive requests and optimize model selection
• Budget management – Track spending and set cost alerts

How to use it: Review price fields to identify expensive requests, compare costs across providers/models, or calculate total spending from logs.

Model ID

What it is: A UUID reference to the Model record in your account, linking the request to model metadata and pricing information.

Why it exists:

• Model metadata linking – Connect requests to model definitions and pricing
• Analytics – Analyze usage by model record
• Pricing accuracy – Verify pricing calculations against model definitions

How to use it: Use model ID to link requests to model records for detailed analytics or pricing verification.

Webhook Deliveries

For async requests and event-driven workflows, Request Logs track webhook delivery attempts, providing complete visibility into notification delivery.

Purpose

Webhook deliveries show how ModelRiver notified your backend about completed async requests. This is essential for:

• Debugging delivery issues – Understand why webhooks failed to reach your endpoint
• Monitoring delivery reliability – Track success rates and identify problematic endpoints
• Retry management – Manually retry failed deliveries when appropriate
• Audit trails – Maintain records of all delivery attempts for compliance

Status Lifecycle

Webhook deliveries progress through these states:

1. Planned – Webhook is queued and scheduled for delivery

   • Why: Indicates the webhook is ready but not yet sent
   • Visual: Gray status badge

2. Delivering – HTTP request to your endpoint is in progress

   • Why: Shows active delivery attempt
   • Visual: Blue status badge

3. Success – Your endpoint returned a 2xx status code

   • Why: Confirms successful delivery
   • Visual: Green status badge

4. Error – Delivery failed (non-2xx response, timeout, or network error)

   • Why: Indicates delivery problem requiring attention
   • Visual: Red status badge

Why status tracking matters: Understanding delivery status helps you:

• Identify endpoints that consistently fail
• Monitor delivery reliability
• Debug webhook processing issues
• Ensure critical notifications are received

Retry Functionality

ModelRiver automatically retries failed webhook deliveries, but you can also manually retry from the Request Logs detail view.

When retry is available

The retry button appears when:

• can_retry is true (calculated by the backend)
• The delivery failed (success is false)
• At least 30 seconds have passed since the delivery was sent

Retry limits

• Maximum 3 attempts total – Original delivery plus 2 retries
• 5-minute window – Retries are only allowed within 5 minutes of the first delivery attempt
• 30-second minimum delay – You must wait at least 30 seconds after a delivery before retrying it
• No duplicate retries – Once a delivery has been retried, it cannot be retried again

Retry rules explained

Why 3 attempts maximum: Prevents infinite retry loops and ensures failed deliveries don't consume excessive resources. Three attempts provide reasonable coverage for transient failures.

Why 5-minute window: Webhook deliveries are time-sensitive. Retrying after 5 minutes may deliver stale data to your backend. The window ensures retries happen while the data is still relevant.

Why 30-second minimum delay: Prevents rapid retry storms that could overwhelm your endpoint. The delay gives your endpoint time to recover from transient issues.

Why no duplicate retries: Once a delivery has been retried, a new delivery record is created. Retrying the original would create confusion and duplicate notifications.

How to retry

1. Navigate to the Request Log detail view
2. Click the webhook delivery in the timeline
3. If retry is available, click the Retry button
4. A new delivery attempt is created and queued

When to retry manually: Use manual retry when:

• Automatic retries have been exhausted
• You've fixed an issue with your endpoint
• You want to test webhook delivery immediately
• You're within the retry window but automatic retries haven't triggered yet

Callback Status

For event-driven workflows, webhook deliveries also show callback status, indicating whether your backend called back to ModelRiver.

Callback status values:

• Progress – Callback is expected but not yet received
• Success – Callback was received successfully
• Error – Callback indicated an error or wasn't received within the 5-minute timeout

Why callback status matters: Event-driven workflows require your backend to call back to ModelRiver with processed data. The callback status shows:

• Whether your backend processed the AI response
• If the callback completed successfully
• Whether the callback timed out

Use Cases & Scenarios

Request Logs support a wide range of use cases. Here are common scenarios and how to use logs effectively.

Debugging Production Issues

Scenario: A user reports that an AI feature isn't working correctly.

Steps:

1. Filter logs to Live mode to focus on production requests
2. Search for requests around the time the issue occurred
3. Click the problematic request to open the detail view
4. Review the timeline to see:
   • Did provider fallbacks trigger? (indicates provider issues)
   • Were there webhook delivery failures? (indicates backend notification issues)
   • Did callbacks complete? (for event-driven workflows)
5. Inspect the request body to verify the prompt/content sent
6. Inspect the response body to see what the AI returned
7. Check error messages in failed model attempts

Why this works: The complete request lifecycle is visible, making it easy to identify where in the flow the issue occurred.

Testing Workflows

Scenario: You want to test a workflow change without affecting production logs.

Steps:

1. Use the Playground to test your workflow
2. Filter logs to Playground (Production) or Playground (Test mode) to review your tests
3. Inspect request/response bodies to verify the workflow behaves correctly
4. Once validated, deploy to production

Why this works: Playground requests are tagged with seed_batch starting with "pg:" or "pg_test_mode:", keeping them separate from production traffic.

Cost Analysis

Scenario: You want to understand your AI spending and optimize costs.

Steps:

1. Filter to Live mode to focus on production costs
2. Review the Price column (if available) to see cost per request
3. Review Token usage to identify high-consumption requests
4. Compare costs across providers/models to find cost-effective options
5. Identify expensive requests and optimize prompts or model selection

Why this works: Token usage and pricing data are captured for every request, enabling detailed cost analysis.

Performance Monitoring

Scenario: You want to monitor request latency and identify slow requests.

Steps:

1. Review the Duration column to see request latency
2. Identify requests with unusually long durations
3. Click slow requests to see:
   • Did fallbacks cause delays? (multiple provider attempts)
   • Which provider/model was slow?
   • Was there a webhook delivery delay?
4. Compare duration across providers to choose faster options
5. Set up alerts for requests exceeding duration thresholds

Why this works: Duration is captured for every request, and the timeline shows the complete request flow, helping identify performance bottlenecks.

Troubleshooting Failures

Scenario: Requests are failing and you need to understand why.

Steps:

1. Filter logs to show only Error status requests
2. Click a failed request to open the detail view
3. Review the timeline to see:
   • Which providers failed and why (check failed model attempts)
   • Whether webhook deliveries failed
   • If callbacks timed out (for event-driven workflows)
4. Inspect error messages in failed attempts
5. Review request/response bodies to identify data quality issues
6. Check if failures are provider-specific or widespread

Why this works: Complete error information is captured, including provider failure reasons, webhook errors, and callback timeouts.

Provider Reliability Analysis

Scenario: You want to understand which providers are most reliable.

Steps:

1. Review logs over a time period (e.g., last 7 days)
2. Count failed model attempts by provider
3. Identify providers that frequently trigger fallbacks
4. Compare success rates across providers
5. Use this data to adjust workflow provider selection

Why this works: Failed model attempts are linked to primary requests via primary_req_id, enabling provider-specific failure analysis.

Webhook Delivery Monitoring

Scenario: You want to ensure webhooks are being delivered reliably.

Steps:

1. Filter to async requests (look for webhook deliveries in timeline)
2. Review webhook delivery status badges
3. Identify failed deliveries and inspect error messages
4. Check delivery duration to identify slow endpoints
5. Use retry functionality for transient failures
6. Monitor callback status for event-driven workflows

Why this works: Every webhook delivery attempt is logged with status, timing, and error information, providing complete delivery visibility.

Best Practices

Follow these best practices to get the most value from Request Logs.

Regular log review

• Review logs daily for anomalies, errors, or performance issues
• Set up alerts for error rate spikes or unusual patterns
• Monitor webhook delivery success rates to catch endpoint issues early

Why: Proactive monitoring catches issues before they impact users.

Use filters effectively

• Separate production from testing – Use filters to focus on relevant request types
• Filter by time period – Focus on recent requests when debugging current issues
• Filter by status – Focus on errors when troubleshooting failures

Why: Filters reduce noise and help you focus on relevant requests.

Monitor failed model frequency

• Track fallback frequency – High fallback rates indicate provider instability
• Identify problematic providers – Use failed model data to adjust provider selection
• Set alerts for fallback rate thresholds

Why: Failed models indicate provider issues that may require workflow adjustments.

Track webhook delivery success rates

• Monitor delivery status – Ensure webhooks reach your endpoints
• Review delivery duration – Identify slow endpoints that may need optimization
• Retry failed deliveries when appropriate

Why: Webhook delivery failures mean your backend isn't receiving notifications, which can break async workflows.

Use seed_batch to separate environments

• Keep test and production separate – Use test mode for integration tests
• Use playground for validation – Test workflow changes in playground before deploying
• Filter appropriately – Use seed batch filters to focus on the right environment

Why: Environment separation prevents test noise from obscuring production issues.

Review token usage for cost optimization

• Identify high-consumption requests – Find requests using excessive tokens
• Compare provider costs – Use token usage and pricing to choose cost-effective options
• Optimize prompts – Reduce input tokens where possible
• Set usage alerts – Get notified when token consumption exceeds thresholds

Why: Token usage directly impacts costs; optimizing usage reduces spending.

Check duration for performance issues

• Monitor request latency – Track duration trends to spot performance degradation
• Identify slow providers – Compare duration across providers to choose faster options
• Set performance alerts – Get notified when requests exceed duration thresholds

Why: Performance directly impacts user experience; monitoring helps maintain acceptable response times.

Inspect request/response bodies for debugging

• Verify prompt content – Ensure prompts are formatted correctly
• Check response quality – Validate AI-generated content meets expectations
• Debug parsing issues – Inspect responses when structured output parsing fails
• Reproduce issues – Use request bodies to recreate issues in testing

Why: Request/response inspection provides the detail needed to debug issues effectively.

Use timeline for complete context

• View the complete request lifecycle – Understand the full story, not just the final result
• Track failover chains – See which providers failed and why
• Monitor webhook/callback flow – Understand async request completion

Why: The timeline provides complete context, essential for understanding complex request flows.

Advanced Features

Request Logs include advanced features for power users and complex workflows.

Primary Request Linking

What it is: Failed provider attempts are linked to successful requests via primary_req_id, creating a complete failover chain.

How it works:

1. When a provider fails, a log entry is created with status: "failed"
2. ModelRiver retries with a fallback provider
3. The successful request is created with a unique ID
4. Failed attempts are updated with primary_req_id pointing to the successful request
5. The timeline shows all linked attempts in chronological order

Why it exists: Understanding the complete failover chain helps you:

• See which providers failed and why
• Understand request resilience (how many attempts were needed)
• Analyze provider reliability
• Calculate true request cost (including failed attempts)

How to use it: When viewing a failed model attempt, the timeline shows the complete chain. The primary request ID links all related attempts together.

Event-Driven Workflows

What it is: Workflows with an event_name enable a three-step flow: AI generation → backend processing → final response.

How it works:

1. Request is made to an async endpoint with a workflow that has event_name
2. AI generates the response
3. Webhook is sent to your backend with type: "task.ai_generated" and callback_url
4. Your backend processes the AI response and calls back to ModelRiver
5. ModelRiver broadcasts the final response to WebSocket channels
6. Request Logs show: main request, webhook delivery, and callback log

Why it exists: Event-driven workflows enable:

• Custom business logic between AI generation and response
• Tool/function calling patterns
• Multi-step workflows with approval gates
• Database enrichment before returning to users

How to use it: Filter logs by event_name to analyze specific event-driven workflows. The timeline shows the complete flow: request → webhook → callback.

Key fields:

• event_name – Identifies the event type
• channel_id – Links request, webhook, and callback together
• callback_status – Shows if callback was received

Sync vs Async Logging

What it is: Requests can be synchronous (immediate response) or asynchronous (response via WebSocket/webhook).

Differences:

• Sync requests (is_async: false):

  • Response returned immediately in HTTP response
  • Logged after provider response is received
  • No webhook deliveries (response is immediate)
  • Simpler logging pattern

• Async requests (is_async: true):

  • Response returned via WebSocket or webhook
  • Logged after provider response, but before final delivery
  • May include webhook deliveries and callbacks
  • More complex logging pattern with multiple components

Why it exists: Different request types have different logging needs. Sync requests are straightforward, while async requests require tracking webhooks and callbacks.

How to use it: Use is_async to filter or analyze sync vs. async requests separately. Async requests will have webhook deliveries in the timeline.

Webhook Retry Logic

What it is: Detailed rules governing when and how webhook deliveries can be retried.

Rules:

1. Maximum 3 attempts total – Original delivery plus 2 retries
2. 5-minute window – Retries only allowed within 5 minutes of first delivery
3. 30-second minimum delay – Must wait 30 seconds after a delivery before retrying
4. No duplicate retries – Once retried, original delivery cannot be retried again
5. Automatic retries – ModelRiver automatically retries with exponential backoff
6. Manual retries – Available from Request Logs when can_retry is true

Why these rules exist:

• 3 attempts maximum – Prevents infinite loops and resource exhaustion
• 5-minute window – Ensures retries happen while data is still relevant
• 30-second delay – Prevents retry storms and gives endpoints time to recover
• No duplicates – Prevents confusion and duplicate notifications

How to use it: Understand the rules to know when retries are available. Use manual retry when automatic retries are exhausted but you're still within the window.

Callback Tracking

What it is: For event-driven workflows, Request Logs track when your backend calls back to ModelRiver.

How it works:

1. Webhook is sent with callback_url
2. Your backend processes the AI response
3. Your backend calls the callback_url with processed data
4. ModelRiver logs the callback as a separate log entry with seed_batch starting with "callback:" or "pg_callback:"
5. The timeline shows the callback after the webhook delivery

Why it exists: Callback tracking shows:

• Whether your backend processed the AI response
• If the callback completed successfully
• Whether the callback timed out (5-minute limit)

How to use it: Review callback logs to verify your backend processing. Check callback status in webhook deliveries to see if callbacks were received.

Callback timeout: If your backend doesn't call back within 5 minutes, ModelRiver:

1. Sends a timeout error to WebSocket channels
2. Logs the timeout event
3. Marks the request as failed

Next Steps

• Explore the Dashboard to see Request Logs in action
• Learn about Workflows to understand how requests are configured
• Review Webhooks for async request patterns
• Check API Integration for request/response formats
• See Troubleshooting for common issues and solutions