Quickstart Guide

Get started with the Monitor API in minutes.

Create an API Key

1. In your organization’s DeepRails API Console, go to API Keys.
   
2. Click Create key, name it, then copy the key.
   
3. (Optional) Save it as the DEEPRAILS_API_KEY environment variable.
   

Install the SDK

Python

pip install deeprails

TypeScript / Node

npm install deeprails

Ruby

gem install deeprails

Go

go get github.com/deeprails/deeprails-go-sdk@latest

Create a Monitor

Before you can send events, you need to create a monitor. A monitor is a container for tracking production events and their evaluations.

Tip: You can also create a monitor via the DeepRails API Console.

Python

from deeprails import DeepRails

# Initialize (env var DEEPRAILS_API_KEY is recommended)
client = DeepRails(token="YOUR_API_KEY")

try:
    # Create a monitor
    monitor = client.monitor.create(
        name="Production Chat Assistant Monitor",
        description="Monitoring our production chatbot responses"
        guardrail_metrics=[
          "completeness",
          "correctness"
        ],
        web_search=True,
        file_search=[
          "file-xxxxxxxxxxxxxxxxxxxxxx"
        ]
    )
    
    print(f"Monitor created:\n{monitor}")

except Exception as e:
    print(f"Error: {e}")

TypeScript / Node

import { DeepRails } from "deeprails";

// Initialize (env var DEEPRAILS_API_KEY is recommended)
const client = new DeepRails("YOUR_API_KEY");

try {
  // Create a monitor
  const monitor = await client.monitor.createMonitor({
    name: 'Production Chat Assistant Monitor',
    description: 'Monitoring our production chatbot responses',
    guardrail_metrics: [
      'completeness',
      'correctness'
    ],
    web_search: true,
    file_search: [
      'file-xxxxxxxxxxxxxxxxxxxxxx'
    ]
  });

  console.log(`Monitor created:\n${monitor}`);
} catch (e) {
  console.error(`Error: ${e}`);
}

Ruby

require "deeprails"

# Initialize (env var DEEPRAILS_API_KEY is recommended)
deeprails = Deeprails::Client.new(
  api_key: ENV["DEEPRAILS_API_KEY"] || "YOUR_API_KEY"
)

begin
  # Create a monitor
  monitor = deeprails.monitor.create(
    name: "Production Chat Assistant Monitor",
    description: "Monitoring our production chatbot responses"
    guardrail_metrics: [
      "completeness",
      "correctness"
    ],
    web_search: true,
    file_search: [
      "file-xxxxxxxxxxxxxxxxxxxxxx"
    ]
  )
  
  puts "Monitor created:\n#{monitor}"
rescue => e
  puts "Error: #{e.message}"
end

Go

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/deeprails/deeprails-go-sdk"
	"github.com/deeprails/deeprails-go-sdk/option"
)

func main() {
	apiKey := "YOUR_API_KEY"

	client := deeprails.NewClient(option.WithAPIKey(apiKey))

	// Create a monitor
	monitorResponse, err := client.Monitor.New(context.TODO(), deeprails.MonitorNewParams{
    Name:             deeprails.F("Production Chat Assistant Monitor"),
    Description:      deeprails.F("Monitoring our production chatbot responses"),
    GuardrailMetrics: deeprails.F([]deeprails.MonitorNewParamsGuardrailMetric{
      deeprails.MonitorNewParamsGuardrailMetricCorrectness,
      deeprails.MonitorNewParamsGuardrailMetricCompleteness,
    }),
    WebSearch:        deeprails.F(true),
    FileSearch:       deeprails.F([]string{"file-xxxxxxxxxxxxxxxxxxxxxx"})
	})

	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("Monitor created with ID: %s\n", monitorResponse.Data.MonitorID)
}

Required Parameters

Field	Type	Description
name	string	The human-readable name of the monitor
guardrail_metrics	string[]	A list of one or more metrics that events associated with this monitor will be evaluated on

Optional Parameters

Field	Type	Description
description	string	A description of the monitor and/or the associated production use case
web_search	bool	Whether or not web search is added as an extended capability for this monitor’s evaluations. Defaults to false
file_search	bool	A list of file IDs to be used for file search in this monitor’s evaluations. If nothing is passed, file search will not be used

Send Your First Monitor Event

Use the SDK to log a production event (input + output). The SDK automatically triggers an evaluation of the guardrail metrics assigned to the monitor and links the result to the event.

Python

from deeprails import DeepRails
import time

# Initialize (env var DEEPRAILS_API_KEY is recommended)
client = DeepRails(token="YOUR_API_KEY")

# Create a monitor event (get the monitor_id from Console → Monitors)
created = client.monitor.submit_event(
    monitor_id="mon_xxxxxxxxxxxxxxxxxxxx",
    model_input={"user_prompt": "Summarize the Paris Agreement in 3 bullets."},
    model_output="• International treaty on climate change...",
    run_mode="economy",
)

print(created)

time.sleep(5)

status = ""
while status is not "completed":
  time.sleep(1)
  event = client.monitor.retrieve_event(event_id=created.event_id)
  status = event.status

print(event.evaluation_result)

TypeScript / Node

import { DeepRails } from "deeprails";

// Initialize (env var DEEPRAILS_API_KEY is recommended)
const client = new DeepRails("YOUR_API_KEY");

// Create a monitor event (get the monitor_id from Console → Monitors)
const created = await client.monitor.submitEvent({
  monitor_id: "mon_xxxxxxxxxxxxxxxxxxxx",
  model_input: { user_prompt: "Summarize the Paris Agreement in 3 bullets." },
  model_output: "• International treaty on climate change...",
  run_mode: "economy",
});

console.log(created);

await new Promise(resolve => setTimeout(resolve, 5000));

let status = "";
while (status !== "completed") {
  await new Promise(resolve => setTimeout(resolve, 1000));
  const event = await client.monitor.retrieveEvent({
    event_id: created.event_id,
  });
  status = event.status;
}

console.log(event.evaluation_result);

Ruby

require "deeprails"

# Initialize (env var DEEPRAILS_API_KEY is recommended)
deeprails = Deeprails::Client.new(
  api_key: ENV["DEEPRAILS_API_KEY"] || "YOUR_API_KEY"
)

# Create a monitor event (get the monitor_id from Console → Monitors)
created = deeprails.monitor.submit_event(
  monitor_id: "mon_xxxxxxxxxxxxxxxxxxxx",
  model_input: { user_prompt: "Summarize the Paris Agreement in 3 bullets." },
  model_output: "• International treaty on climate change...",
  run_mode: "economy",
)

puts created

sleep(5)

status = ""
while status != "completed"
  sleep(1)
  event = deeprails.monitor.retrieve_event(event_id: created.event_id)
  status = event.status
end

puts event.evaluation_result

Go

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/deeprails/deeprails-go-sdk"
	"github.com/deeprails/deeprails-go-sdk/option"
)

func main() {
	apiKey := "YOUR_API_KEY"

	client := deeprails.NewClient(option.WithAPIKey(apiKey))

	// Create a monitor event (get the monitor_id from Console → Monitors)
	created, err := client.Monitor.SubmitEvent(context.TODO(),
		"mon_xxxxxxxxxxxxxxxxxxxx",
		deeprails.MonitorSubmitEventParams{
			ModelInput: deeprails.F(deeprails.MonitorSubmitEventParamsModelInput{
				UserPrompt: deeprails.F("Summarize the Paris Agreement in 3 bullets."),
			}),
			ModelOutput: deeprails.F("• International treaty on climate change..."),
      RunMode: deeprails.F("economy"),
		})

	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%+v\n", created)

	time.Sleep(5 * time.Second)

	var event *deeprails.Evaluation
	for event == nil || event.EvaluationStatus != deeprails.EvaluationEvaluationStatusCompleted {
		time.Sleep(1 * time.Second)
		var err error
		event, err = client.Evaluate.Get(context.TODO(), created.Data.EvaluationID)
		if err != nil {
			log.Fatal(err)
		}
	}

	fmt.Printf("%+v\n", event.EvaluationResult)
}

Required Parameters

Field	Type	Description
monitor_id	string	The ID of the monitor to receive the event (find it in Console → Monitor → Manage Monitors).
model_input	object	Must include at least system_prompt or user_prompt.
model_output	string	The LLM output to be evaluated and recorded with the event.

Retrieve Monitor Data

You can retrieve monitor details including stats on evaluation progress.

Python

from deeprails import DeepRails

client = DeepRails(token="YOUR_API_KEY")

try:
    # Get monitor details
    monitor = client.monitor.retrieve(monitor_id="mon_xxxxxxxxxxxxxxxxxxxx")
    print(monitor)
except Exception as e:
    print(f"Error: {e}")

TypeScript / Node

import { DeepRails } from "deeprails";

const client = new DeepRails("YOUR_API_KEY");

try {
  // Get monitor details
  const monitor = await client.monitor.retrieve({
    monitor_id: "mon_xxxxxxxxxxxxxxxxxxxx",
  });
  console.log(monitor);
} catch (e) {
  console.error(`Error: ${e}`);
}

Ruby

require "deeprails"

deeprails = Deeprails::Client.new(
  api_key: ENV["DEEPRAILS_API_KEY"] || "YOUR_API_KEY"
)

begin
  # Get monitor details
  monitor = deeprails.monitor.retrieve(
    monitor_id: "mon_xxxxxxxxxxxxxxxxxxxx"
  )
  puts monitor
rescue => e
  puts "Error: #{e.message}"
end

Go

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/deeprails/deeprails-go-sdk"
	"github.com/deeprails/deeprails-go-sdk/option"
)

func main() {
	apiKey := "YOUR_API_KEY"

	client := deeprails.NewClient(option.WithAPIKey(apiKey))

	// Get monitor details
	monitor, err := client.Monitor.Get(context.TODO(), "mon_xxxxxxxxxxxxxxxxxxxx", deeprails.MonitorGetParams{})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("%+v\n", monitor)
}

Check Monitor Analytics via the API Console

1. Open DeepRails API Console → Monitor → Data.
   
2. Filter by model, time range, or search by monitor_id to find events.
   
3. Open any event to see the linked evaluation scores and rationales.
   

Next Steps

Learn About Guardrails

Explore the metrics behind evaluations—correctness, safety, completeness, and more.

Monitor Overview

Learn core Monitor concepts and how it fits into your flow.