---
title: Track scheduled checks
description: Record recurring check results in tzTrack, group repeat findings, and track recovery without creating a new issue for every run.
slug: /guides/track-scheduled-checks
order: 3
visibility: public
redirects_from: []
---

# Track scheduled checks

Prompt:

> Every night, check the backups and tell me about anything wrong.

Also works: "Run the link check each morning and keep track of what breaks." "Watch the disk space on the servers."

Keep findings from recurring checks in one shared record. Later runs add evidence to an existing issue, so you can see what remains unresolved. Schedule the checks in your AI tool or another scheduler; tzTrack records their findings.

The Turn Zero connection lists tzTrack tools with `tztrack_` before the name: `find` is `tztrack_find`. This page uses the shorter names. [The tools](/tztrack/reference/the-tools/) lists the full names.

## What your AI tool does

- Reads previous findings before running the checks.
- Uses stable problem identifiers to help group recurring failures.
- Records new observations, recovery evidence, and actions that need you.
- Reports which issues remain open after the run.

## What you need

- An AI tool or another scheduler that can run the checks. tzTrack does not schedule or run them.
- Access for that runner to report findings to the intended space.

## Before your AI starts

- Confirm the schedule, checks, and permissions match the person's request.
- Select the space and a label such as `nightly-checks`.
- Use a consistent reporting identity and `problem_key` for the same check and target, such as `backup-age:orders-db`.
- Confirm permission to close issues if recovery handling will do so; closing requires `owner` access.

## Steps

These instructions are for your AI tool.

### 1. Read what earlier runs found

List the check's issues with `find` and the chosen `label`. Read the relevant issue before changing it, including its state and any claim.

### 2. Run the checks

Run the checks through the configured runner. Record the result, run reference, and useful evidence. Keep dates and run numbers out of `problem_key`; they belong in the observation, not the problem's identity.

### 3. Record each problem

For a new failure, use `raise` with kind `bug`, the stable `problem_key`, the label in `labels`, and what the check observed. A problem key identifies a recurring problem; a request's retry key serves a different purpose.

Read the response. A repeat can reuse an issue or return an unchanged retry; it does not guarantee a new report. Use `comment` to add current-run observations to a known issue.

If a previously completed check fails again, read its closed issue before deciding whether to reopen it with a reason. Do not assume a repeat report automatically reopens a tracked software fix.

### 4. Record what needs the person

If only the space's owner can act, use `waiting_for: person` and explain what is needed. Use an outside dependency for an external event. [Waiting and claims](/tztrack/concepts/waiting-and-claims/) explains the options.

### 5. Record recovery

Add the passing result and run reference to the issue. If the problem is resolved and you have permission, close it with outcome `done` and the recovery evidence. Reopen an evidence-waiting issue before completing it.

Do not use `verified` merely because one run passed. A tracked software fix follows the separate [release-verification process](/tztrack/concepts/issues-and-kinds/#why-fixed-is-not-closed).

## Expected result

The issue record shows recurring failures, the latest observations, and recovery evidence. Your AI can report what is still wrong and what needs the person's attention.

## Refusals

Common refusals are below; [Refusals](/tztrack/reference/refusals/) lists the rest.

| Refusal | Status | Cause | Remedy |
| --- | --- | --- | --- |
| `credential_refused` | 401 | The runner's credential expired or was revoked. | Restore its authorized connection before retrying. |
| `rate_limited` | 429 | Too many requests. | Wait for the rate window to reset, then retry. |
| `grant_required` | 403 | The runner cannot perform the requested action. | Check its access level; reporting and closing have different permissions. |

## Related

- [Issues and kinds](/tztrack/concepts/issues-and-kinds/) explains reports and outcomes.
- [Waiting and claims](/tztrack/concepts/waiting-and-claims/) explains waiting for your person.
- [The tools](/tztrack/reference/the-tools/) lists `raise` and `close`.