Inspect runs

Every execution of a monitor produces a run, whether or not it found anything. Read runs to tell a quiet monitor from a broken one. The examples below start from a monitor you already created — see the Quickstart.

from seltz import Seltz

client = Seltz()
monitor_id = client.monitor.list(name="my-example-monitor").monitors[0].monitor_id

import { Seltz } from "seltz";

const client = new Seltz();
const monitorId = (await client.monitor.list({ name: "my-example-monitor" })).monitors[0].monitorId;

List runs

Run history is newest first, so the first run in a page is the latest. Runs page on run_id, not on a cursor token: page back with before, or ask for ascending order and walk forward with since. Both cursors are exclusive, and has_more tells you whether more remain.

from seltz import SortOrder

page = client.monitor.list_runs(monitor_id, limit=10)

if page.runs:
    latest = page.runs[0]
    print(latest.run_id, latest.status, latest.record_count)
    print(latest.requests_ok, "of", latest.requests_total, "requests succeeded")

# Oldest first instead
ascending = client.monitor.list_runs(
    monitor_id, limit=10, sort=SortOrder.SORT_ORDER_ASC
)

import { SortOrder } from "seltz";

const page = await client.monitor.listRuns(monitorId, { limit: 10 });

const latest = page.runs[0];
if (latest) {
  console.log(latest.runId, latest.status, latest.recordCount);
  console.log(latest.requestsOk, "of", latest.requestsTotal, "requests succeeded");
}

// Oldest first instead
const ascending = await client.monitor.listRuns(monitorId, {
  limit: 10,
  sort: SortOrder.ASC,
});

MONITOR_ID="your-monitor-id"

curl "https://api.seltz.ai/v1/monitors/$MONITOR_ID/runs?limit=10&sort=desc" \
  -H "x-api-key: $SELTZ_API_KEY"

Read one run

Fetch a single run by id when a webhook delivery tells you one finished.

from seltz import Seltz

client = Seltz()
monitor_id = client.monitor.list(name="my-example-monitor").monitors[0].monitor_id
run_id = client.monitor.list_runs(monitor_id, limit=1).runs[0].run_id

response = client.monitor.get_run(monitor_id, run_id)
run = response.run

import { Seltz } from "seltz";

const client = new Seltz();
const monitorId = (await client.monitor.list({ name: "my-example-monitor" })).monitors[0].monitorId;
const runId = (await client.monitor.listRuns(monitorId, { limit: 1 })).runs[0].runId;

const response = await client.monitor.getRun(monitorId, runId);
const run = response.run;

MONITOR_ID="your-monitor-id"
RUN_ID="your-run-id"

curl "https://api.seltz.ai/v1/monitors/$MONITOR_ID/runs/$RUN_ID" \
  -H "x-api-key: $SELTZ_API_KEY"

A run carries requests_total, requests_ok and requests_failed, which say how many of its searches worked. Which ones is a separate call.

Read a run’s per-request breakdown

list_run_requests returns one entry per search request on the config the run executed. It is not paged — there is no cursor and no has_more, because a monitor holds at most 1000 requests and the whole set comes back at once.

from seltz import Seltz

client = Seltz()
monitor_id = client.monitor.list(name="my-example-monitor").monitors[0].monitor_id
run_id = client.monitor.list_runs(monitor_id, limit=1).runs[0].run_id

response = client.monitor.list_run_requests(monitor_id, run_id)

for request in response.requests:
    print(request.request_id, request.status)
    print(" returned", request.results_returned, "new", request.new_records)
    if request.reason:
        print(" reason:", request.reason)

import { Seltz } from "seltz";

const client = new Seltz();
const monitorId = (await client.monitor.list({ name: "my-example-monitor" })).monitors[0].monitorId;
const runId = (await client.monitor.listRuns(monitorId, { limit: 1 })).runs[0].runId;

const response = await client.monitor.listRunRequests(monitorId, runId);

for (const request of response.requests) {
  console.log(request.requestId, request.status);
  console.log(" returned", request.resultsReturned, "new", request.newRecords);
  if (request.reason) console.log(" reason:", request.reason);
}

MONITOR_ID="your-monitor-id"
RUN_ID="your-run-id"

curl "https://api.seltz.ai/v1/monitors/$MONITOR_ID/runs/$RUN_ID/requests" \
  -H "x-api-key: $SELTZ_API_KEY"

results_returned against new_records is what separates “working, nothing new” from “this query returns nothing” from “this request is failing”:

results_returned high, new_records zero — the query works and the web has not moved. Nothing to do.
results_returned zero across every run — the query itself matches nothing. Rewrite it.
status reports the request as failing — the search did not complete. reason carries prose explaining it; there is no error code.

Read one run’s records

first_record_id and last_record_id on a run are a bound, not a dense sequence. To read one run’s records, ask for them rather than doing arithmetic on ids.

from seltz import Seltz

client = Seltz()
monitor_id = client.monitor.list(name="my-example-monitor").monitors[0].monitor_id
run_id = client.monitor.list_runs(monitor_id, limit=1).runs[0].run_id

page = client.monitor.list_run_records(monitor_id, run_id, limit=100)

for record in page.records:
    print(record.record_id, record.search_result.document.url)

import { Seltz } from "seltz";

const client = new Seltz();
const monitorId = (await client.monitor.list({ name: "my-example-monitor" })).monitors[0].monitorId;
const runId = (await client.monitor.listRuns(monitorId, { limit: 1 })).runs[0].runId;

const page = await client.monitor.listRunRecords(monitorId, runId, {
  limit: 100,
});

for (const record of page.records) {
  if (record.payload.case !== "searchResult") continue;
  console.log(record.recordId, record.payload.value.document?.url);
}

MONITOR_ID="your-monitor-id"
RUN_ID="your-run-id"

curl "https://api.seltz.ai/v1/monitors/$MONITOR_ID/runs/$RUN_ID/records?limit=100" \
  -H "x-api-key: $SELTZ_API_KEY"

This reads one page. A first run is the largest a monitor produces, so page with since while has_more is set.

Getting Started

Web Tools

Data

Tutorials

Chat

Integrations

SDKs

Inspect runs

List runs

Read one run

Read a run’s per-request breakdown

Read one run’s records

​List runs

​Read one run

​Read a run’s per-request breakdown

​Read one run’s records

List runs

Read one run

Read a run’s per-request breakdown

Read one run’s records