Operations

Create a monitor

Create a monitor for one query. It is all or nothing: if the call fails, no monitor exists.

POST/v1/monitors

Send your API key as Authorization: Bearer. See Authentication. How each option works: Monitors.

Request body

querystring: What to watch for, as a plain sentence. You cannot change it later.
options.frequencystringdefault "1d": How often Telem runs the query: 1h, 6h, 12h, 1d or 7d.
options.include_domainsstring[]1 to 20 items: Only results from these sites and their subdomains, such as sec.gov. Host names only.
options.searchobject: Also search the web for the query on each run, with these options. {} uses the default search. See Monitors.
options.search.num_resultsintegerdefault 101 to 20: Results for each provider on each run.
options.search.tierstringdefault "default"one of minimalist, default, extended, max: Which fields each result has.
webhook_urlstringat most 2048 characters: An https URL. Telem sends the new results to it. See Get results by webhook.
ttlstring: How long the monitor lives, such as 12h or 7d, at most 30d. Without it, the monitor does not expire.
agentbooleandefault true: The monitor agent checks every result against the query and keeps the ones that match. You read what it keeps in the console. Send false to create the monitor without an agent.

More fields: metadata

metadataobject: Query lineage keys, as in a search.

Response

201

idstring (UUID): The ID of the monitor.
querystring: What the monitor watches for.
frequencystring: How often Telem runs the query.
statusstringone of active, paused, ended: active: Telem runs the query on the schedule. paused: you paused it. ended: its end time passed, or its API key was revoked or expired, and it does not run again. A monitor that nobody polls stops its runs but still shows active: see Monitors.
session_idstring (UUID): The session where Telem records your polls.
created_atstring (date-time): When you created the monitor.
last_polled_atstring (date-time) or null: Your last poll or delivered webhook, or null.
expires_atstring (date-time) or null: When the monitor ends, or null without a ttl.
webhook_urlstring or null: Where Telem sends new results, or null.
webhook_secretstring or null: The secret to check webhook requests with. Only the response that sets webhook_url has it, so keep it.
agent_notestring or null: Only in the answer to a create: why the monitor agent did not start, or null. The monitor then runs without an agent.

Errors

Status	Code	When
`400`	`invalid_request`	A field is not correct, such as a frequency that is not in the list, or a search provider refused the request. In that case, sending it unchanged will not help.
`400`	`invalid_session`	The session in `metadata` is not correct.
`402`	`payment_required`	The account cannot pay for the monitor. The message says why.
`422`	`invalid_request`	The body is not valid. For example: an unknown field, an empty `query`, a `webhook_url` that is not `https`, a `ttl` that is not correct, or an `options.search` option that the monitor sets itself.
`401`	`unauthorized`	The API key is missing or not valid.
`403`		The API key has no access to monitors.
`429`	`rate_limited`	Your key went over its requests-per-minute cap, or Telem is busy. Wait for the seconds in `Retry-After`, then try again.
`503`	`unavailable`	Telem cannot run monitors now. Try again later.
`500`	`internal_error`	Telem could not create the monitor. No monitor exists. Try again.
`502`	`unavailable`	The monitor failed. You can send the same request again.

What each error means and what to do: Errors.

Request

curl -X POST "https://router.telem.ai/v1/monitors" \
  -H "Authorization: Bearer $TELEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Nvidia files a new 8-K with the SEC",
    "options": {"frequency": "1h"}
  }'

from telem import Telem

client = Telem()
monitor = client.monitors.create(
    "Nvidia files a new 8-K with the SEC",
    frequency="1h",
)
print(monitor.id)

import { Telem } from "@telemai/sdk"

const telem = new Telem()
const monitor = await telem.monitors.create("Nvidia files a new 8-K with the SEC", {
  frequency: "1h",
})
console.log(monitor.id)

Response

{
  "id": "6f1c2a4e-3b7d-4c51-9e0a-8d2f6b1c7a90",
  "query": "Nvidia files a new 8-K with the SEC",
  "frequency": "1h",
  "status": "active",
  "session_id": "a2d9e1f0-5c3b-4a7d-8e6f-1b2c3d4e5f60",
  "created_at": "2026-10-11T09:00:00Z",
  "last_polled_at": null,
  "expires_at": "2026-10-18T09:00:00Z",
  "webhook_url": null,
  "webhook_secret": null,
  "agent_note": null
}

An example built from the response schema.

{
  "error": {
    "code": "invalid_request",
    "message": "frequency '2h' is not supported"
  }
}

A real response to "frequency": "2h".

{
  "error": {
    "code": "invalid_request",
    "message": "Extra inputs are not permitted",
    "param": "colour"
  }
}

A real response to a body with an unknown field.

Was this page helpful?