Operations

Poll a monitor

Get the results that are new since the last poll, in the same shape as a search response. The poll is recorded in the monitor's session unless the body names a session_id or lineage metadata.

POST/v1/monitors/{monitor_id}/poll

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

Path parameter

monitor_idstring (UUID): The ID of the monitor, from the response that created it.

Request body

The body is optional.

session_idstring (UUID): Record the poll in this session. Without session_id and metadata, Telem records it in the monitor's session.
metadataobject: Query lineage keys, as in a search.

Response

200The results that are new since your last poll, in the same shape as a Search response.

statusstring: The state of the call, such as succeeded.
preprocessor_runs[]object[]: One run for each provider and query. A provider that fails does not fail the call: its run has an error.
preprocessor_runs[].preprocessor_namestring: The provider of the run.
preprocessor_runs[].querystring: The query of the run. batch_index is its place in a batch.
preprocessor_runs[].output_payload.results[]array: The results of the run. They have the same fields whichever provider found them: see the fields per tier.
preprocessor_runs[].errorobject or null: Why the run failed, or null.
session_idstring (UUID): The session that recorded the call. Send it back as session_id to add the next call to it.
interaction_idstring (UUID): The ID of this call.
normalized_schema_versioninteger or null: The version of the result format: 2.

created_at, completed_at: when Telem received the call and when it finished.

The response also has instance_id, trajectory_id, parent_trajectory_id, trajectory_goal, postprocessor_runs, missing_snapshots, client_advisory. You do not need them to read the results.

Errors

Status	Code	When
`400`	`invalid_request`	`session_id` belongs to another monitor: `error.param` is `session_id`. Or a provider no longer has this monitor: polling again will not help, so end the monitor and create a new one.
`400`	`invalid_session`	The session in `metadata` is not correct.
`401`	`unauthorized`	The API key is missing or not valid.
`403`		The API key has no access to monitors.
`404`	`not_found`	The monitor does not exist, or another API key created it.
`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.
`409`	`poll_in_progress`	Another call uses this monitor now. Try again.
`409`	`monitor_ended`	The monitor has ended: its end time passed, or its API key was revoked or expired. Its results stay readable. Create a new monitor.
`409`	`missing_snapshots`	The request names earlier context that Telem does not have. Nothing ran. Send it again with that context.
`502`	`unavailable`	Every run of the poll failed. Try again.

What each error means and what to do: Errors.

Request

curl -X POST "https://router.telem.ai/v1/monitors/$MONITOR_ID/poll" \
  -H "Authorization: Bearer $TELEM_API_KEY"

response = client.monitors.poll(monitor_id)
for result in response.results:
    print(result.title, result.url)

const response = await telem.monitors.poll(monitorId)
for (const result of response.results) console.log(result.title, result.url)

Response

{
  "status": "succeeded",
  "preprocessor_runs": [
    {
      "preprocessor_name": "…",
      "status": "succeeded",
      "output_payload": {
        "results": [
          {
            "rank": 1,
            "url": "…",
            "title": "…"
          }
        ],
        "warnings": []
      },
      "error": null
    }
  ],
  "normalized_schema_version": 2
}

The shape of the response. The warnings a poll can have are on Monitors.

{
  "error": {
    "code": "not_found",
    "message": "Monitor not found"
  }
}

A real response.

Was this page helpful?