# Scheduled screenings > Run the same screening on your agent every day, every week, or whenever its configuration changes, with spend caps that pause it. A screening tells you how an agent performs today. A scheduled screening tells you how it performs over time. It runs the same suite on your agent on a cadence you choose, and each finished screening adds a point to the agent's history, so a drop in quality shows up without anyone remembering to re-run it. Scheduled screenings are available on Pro (up to 3 schedules), Team (up to 20 schedules per workspace) and Enterprise (no fixed limit). Free plans cannot create schedules. See [Pricing](/docs/guides/pricing). Cadences [#cadences] Every schedule uses one of three cadences: * **Daily.** Runs once a day at the hour you pick. Times are in UTC. * **Weekly.** Runs once a week on the weekday and hour you pick. * **On blueprint change.** Runs when the agent's declared configuration changes, about a minute after Badge records the new version. Use it to re-check an agent every time you change its model, prompt or tools. A change made by a scheduled screening never starts another one. Each blueprint-triggered schedule runs at most once every 6 hours, so an agent with several of these schedules can be screened more than once in that window, up to the limit of your plan. Each occurrence runs the suite between 1 and 5 times (the "runs per screening" setting). More repeats smooth out a noisy agent, at the cost of more runs against your monthly allowance. Each schedule also has an overlap window, from 15 minutes to 24 hours (2 hours by default). Badge will not start a second occurrence for the same agent while the previous one's window is still open. Spend caps [#spend-caps] You can set two optional caps in US dollars: * **Per-run cap.** Pauses the schedule if any single run in a screening cost more than this. * **Monthly cap.** Pauses the schedule once the month-to-date spend for this schedule reaches this amount. The month is the UTC calendar month. Badge counts the cost of each run from the figures it has for it. When a measured cost is available it is used; otherwise Badge uses the cost the agent reports for itself. A self-reported cost can understate what the agent actually spends. This is Badge's recorded figure, not an invoice from your model provider or host. Caps are checked after a screening finishes, so a screening can end above a cap. The one that crosses a cap still completes and is counted in full. The schedule then pauses before its next occurrence. Paused: what it means [#paused-what-it-means] A paused schedule does not run. Its settings and history are kept. The owner gets an email once, when a schedule moves from active to paused. Each pause shows a reason on the agent's **Manage** page: * **Paused: budget.** A cap was reached. Either one run in a screening cost more than the per-run cap, or the month's spend reached the monthly cap. To resume, raise the cap or clear it, then turn the schedule back on. If the monthly cap is still reached, the schedule pauses again at its next occurrence. The monthly total resets at the start of the next UTC month. * **Paused: endpoint failures.** Three screenings in a row could not reach your agent or got errors back from it. Check that the endpoint is up and answering, then turn the schedule back on. * **Paused: invalid request.** Three runs in a row were refused because the request is no longer valid for this agent: the schedule's suite or task selection was retired, or the agent's credential must be reconnected. Edit the schedule or your agent (reconnect the credential if asked), then turn the schedule back on. * **Paused: access.** You no longer have edit access to the agent, or the agent was moved out of the workspace or personal scope the schedule was created in. Restore access, then turn the schedule back on. If the agent was deleted, delete the schedule. * **Paused: plan.** Your current plan no longer includes this many scheduled screenings, or the team's plan is no longer active. Upgrade, or pause or delete other schedules until the count fits, then turn this one back on. On the Free plan no schedule can be resumed. * **Paused by you.** You turned the schedule off. If your own account was deactivated, the schedule also shows this reason; reactivate the account, then turn the schedule back on. Turning a schedule back on schedules the next future occurrence. It does not run the ones you missed. Anyone with edit access to the agent can pause a schedule. Only the person who created a schedule can turn it back on, because it runs as them and spends their quota. If you lost edit access to the agent, you can still see, pause and delete your own schedules, but you cannot reconfigure or resume them until access is restored. Set one up [#set-one-up] On the agent's **Manage** page, find the **Scheduled screenings** card. Choose the cadence, the hour (UTC), the runs per screening and any caps, then save. The history under the card lists each scheduled screening with its runs, pass and fail counts and cost. On the Free plan the form shows the card and the first attempt to create a schedule is refused, with a link to plans. The form then stays locked until you reload the page. You can also create one from an MCP client with the `schedule_suite` tool. `schedule_suite` (MCP) [#schedule_suite-mcp] Requires a Badge API key (`BADGE_API_KEY`). The tool takes the same settings as the card: | Input | Required | Notes | | -------------------------- | ----------- | ------------------------------------------------------------ | | `agent_id` | Yes | An agent you own or can edit. | | `cadence` | Yes | `daily`, `weekly` or `on_blueprint_change`. | | `suite_id` or `task_ids` | No | Choose one. Omit both to screen the full catalogue. | | `hour_utc` | No | 0 to 23. Default 0. | | `weekday` | Weekly only | 0 is Monday through 6 is Sunday. | | `run_count_k` | No | 1 to 5 runs per screening. Default 1. | | `budget_cap_usd_per_run` | No | Pause if any single run in a screening costs more than this. | | `budget_cap_usd_per_month` | No | Pause once the month's spend reaches this. | Example call, a weekly screening every Monday at 06:00 UTC with a $25 monthly cap: ```json { "agent_id": "a1b2c3d4-0000-4000-8000-000000000001", "cadence": "weekly", "weekday": 0, "hour_utc": 6, "suite_id": "a1b2c3d4-0000-4000-8000-000000000002", "run_count_k": 1, "budget_cap_usd_per_month": 25 } ``` The tool returns the created schedule: its cadence, its next run, its caps and a link to manage it. API [#api] All routes are under `/api/v1`. They return 404 while scheduled screenings are turned off for the deployment. Reads need a session or an API key with `read` scope. Writes need `write` scope and edit access to the agent. | Method | Path | Purpose | | -------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | `POST` | `/agents/{agent_id}/schedules` | Create a schedule. Returns 201. | | `GET` | `/agents/{agent_id}/schedules` | List the schedules for an agent. | | `GET` | `/schedules/{schedule_id}` | Read one schedule, including its caps, spend and pause reason. | | `PATCH` | `/schedules/{schedule_id}` | Change any setting, or set `is_active` to pause or resume. Only the schedule's creator can resume it. | | `DELETE` | `/schedules/{schedule_id}` | Delete the schedule. Returns 204. Past screenings are kept. | | `GET` | `/schedules/{schedule_id}/history?page=1&page_size=20` | Past scheduled screenings for the agent, newest first. `page_size` is at most 100. | Example: resume a paused schedule. ```bash curl -X PATCH "https://badgeia.com/api/v1/schedules/$SCHEDULE_ID" \ -H "Authorization: Bearer $BADGE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"is_active": true}' ``` Revoking an API key does not stop a schedule. A schedule belongs to your account and runs as you, not as the key. To stop it, pause or delete the schedule. Removing a schedule does not remove the screenings it already ran.