Skip to main content
A schedule creates a session on a recurring cadence: a five-field cron expression evaluated in an IANA timezone, paired with a session template that is re-resolved on every fire. Use it for recurring work like a daily scrape or an hourly check. Manage schedules with the CRUD API. Each one has a name, a timing, and a session_request template: 
curl -X POST https://agp.eu.hcompany.ai/api/v2/schedules \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "morning-market-scan",
    "timing": {"expression": "0 9 * * 1-5", "timezone": "Europe/Paris"},
    "session_request": {
      "agent": "h/web-surfer-flash",
      "messages": [
        {"type": "user_message", "message": "Scan new apartment listings in Paris 11e and summarize the top five"}
      ]
    }
  }'

​
Timing

Timing field
"timing": {
  "type": "cron",
  "expression": "0 9 * * 1-5",
  "timezone": "Europe/Paris"
}
The expression is standard five-field cron (minute hour day-of-month month day-of-week), evaluated in the given timezone, so 0 9 * * 1-5 fires at 09:00 Paris time every weekday, across daylight-saving changes. An expression may not fire more often than once every 5 minutes. The type tag is optional on requests; "cron" is the default and only variant today. The schedule object reports its upcoming fires in next_run_times (the next 5, empty while paused).

​
The session template

session_request takes the same shape as the Create session body. It is stored as a template and re-resolved on every fire, so a catalog agent like "h/web-surfer-flash" always runs its current version. Two restrictions apply: the template must contain at least one initial message, and it may not set parent_session_id. If the template does not set max_time_s, scheduled sessions default to 3600 seconds.

​
Fire outcomes

Every fire is recorded in the schedule’s run history, whether or not it created a session:
StatusMeaning
createdA session was created; the run carries its session_id.
skipped_overlapThe session from a previous fire was still active, so this fire was skipped.
skipped_quotaYour organization was at quota, so this fire was skipped.
errorSession creation failed; the run carries the error detail.
Fires do not queue behind each other: a skipped fire is skipped for good, and the schedule simply fires again at the next cadence point. Run history is retained for 90 days.

​
Pausing and failures

Pause stops future fires without deleting the schedule, and Resume recomputes the next fire from now. After 5 consecutive error fires, the schedule is paused automatically with an explanatory pause_note. A successful fire or a resume resets the counter. Trigger fires a schedule once immediately, even while paused, without affecting the regular cadence. Use it to test a template before the first scheduled fire.

​
Consuming the results

Nobody is polling a scheduled session, so pair schedules with a webhook: you receive a signed event when each scheduled session reaches a settled state, then fetch its answer with Get session. For batch inspection, list a schedule’s sessions with the schedule_id filter on List sessions; each fire’s run record also links to its session.

​
Constraints

  • An organization can have up to 20 schedules.
  • The cron expression may not fire more often than once every 5 minutes.
  • Deleting a schedule stops future fires; sessions already created keep running.