For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested

Agents API

Agents SDK

ChatKit

API Dashboard
Try ChatGPT

Scheduled automations

Run agent work on a schedule or let an agent schedule future work.

Use scheduled automations to kick off agent sessions on a cron schedule. You can also enable the automations tool for your agents, so they can schedule tasks in the course of their work.

  • Automate sessions on a cron schedule

    Use a cron expression and time zone to start new sessions or continue an existing session.

  • Enable agents to create automations

    Add the automations tool so an agent can schedule follow-ups in its current session.

  • Monitor automation invocations

    Each invocation records an attempt to send a task to a session. Inspect its status and session ID.
Automate sessions on a cron schedule
import OpenAI from "openai";

const client = new OpenAI();
const automation = await client.beta.agents.automations.create({
  type: "periodic",
  name: "Daily session",
  expression: "0 10 * * *",
  timezone: "America/New_York",
  target: {
    type: "new_session",
    agent_id: "agt_123",
    environment: { type: "openai_hosted" },
    input: [
      {
        role: "user",
        content: [
          {
            type: "input_text",
            text: "Summarize the current status and next steps.",
          },
        ],
      },
    ],
  },
});
console.log(automation);

API resources

  • Agents

    /v1/agents

    Define the instructions and tools for the task.

  • Automations

    /v1/agents/automations

    Save when to run and which session to use.

  • Invocations

    /v1/agents/automations/{automation_id}/invocations

    See when a task was sent and which session received it.

  • Sessions

    /v1/agents/sessions

    Run the task with conversation history and tools.

  • Session events

    /v1/agents/sessions/{session_id}/events

    Follow progress and collect the result.

Use cases

How it works

An automation is a saved schedule for agent work. The Agents API stores the schedule and sends each task to its target session:

  1. Define the work. Choose when it should run and whether each run starts a new session or continues an existing one.
  2. Send the task. Each run creates an invocation, a record of the attempt to send the task to its target session. If that session is busy, the task waits.
  3. Follow the result. The agent works with the session’s tools and context. Follow session events to track progress and collect results. The session receiving the task doesn’t mean the agent has finished the work.

Your application can create, update, pause, or delete schedules through the API. With the automations tool enabled, an agent can also schedule its own next check in its current session.

Choose the session and schedule

Choose a target based on whether the task needs earlier conversation history:

Target Use it for Required configuration
new_session Independent work, such as a monthly spending review. An agent, an environment, and initial messages in target.input.
existing_session Follow-up work that needs the session’s previous findings. A session ID and reminder text in target.instructions.

Choose timing independently of the target:

Type Timing fields Example
periodic expression and timezone Every day at 10 AM in America/New_York.
once run_at One check at a future time specified as a Unix timestamp in seconds.

Both schedule types work with either target. Creating an automation saves it with status active; it doesn’t run the task immediately. A periodic automation’s first occurrence is scheduled for the next matching time.

Schedule daily suggestions

Before creating the automation, create an agent with instructions and tools for the task, including access to the user’s calendar, tasks, and messages. See Reuse an agent across sessions.

The SDKs include the OpenAI-Beta: agents=v1 header; include it when calling the API with cURL.

Here’s an example of how to create an automation to start a new session for 10 AM each day in New York:

Schedule daily suggestions
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Daily suggestions",
    expression="0 10 * * *",
    timezone="America/New_York",
    target={
        "type": "new_session",
        "agent_id": "agt_123",
        "environment": {"type": "openai_hosted"},
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": (
                            "Review my calendar, tasks, and recent messages for today. "
                            "Suggest the most useful actions I could take today, "
                            "with a short reason for each."
                        ),
                    }
                ],
            }
        ],
    },
)
print(automation.to_json())

Save the returned automation id to inspect or manage the schedule later. Each invocation starts a new conversation. The environment configuration above provisions an OpenAI-hosted sandbox for that session.

You can supply inline agent configuration in target.agent instead of a saved target.agent_id. Supply exactly one of these fields. Put the initial messages inside target.input, not at the top level of the request. Include at least one message with nonempty text or an image URL.

Review spending each month

The same approach works for a monthly spending review. Give the saved agent access to the user’s financial records, then schedule a new session for 9 AM on the first day of each month:

Schedule a monthly spending review
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Monthly spending review",
    expression="0 9 1 * *",
    timezone="America/New_York",
    target={
        "type": "new_session",
        "agent_id": "agt_123",
        "environment": {"type": "openai_hosted"},
        "input": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "input_text",
                        "text": (
                            "Review my spending for the previous month. Flag unused "
                            "subscriptions, price increases, and other potential "
                            "savings for me to review."
                        ),
                    }
                ],
            }
        ],
    },
)
print(automation.to_json())

Set recurring timing

Use a five-field cron expression with a named time zone:

Expression Schedule
0 10 * * * Every day at 10 AM
0 */2 * * * Every two hours
0 9 1 * * First day of each month at 9 AM
0 9 * * MON-FRI Monday through Friday at 9 AM

The time zone determines how to interpret the expression. Use UTC for a UTC schedule or an IANA time zone such as America/New_York for a local schedule. Don’t include run_at in a periodic automation.

A cron schedule follows clock times in the selected time zone. For example, 0 */3 * * * schedules runs at midnight, 3 AM, 6 AM, and every three hours after that, rather than every three hours from creation.

The schedule specifies the intended time. The Agents API adds a small randomized delay to recurring runs to spread load. The task can wait longer if the target session is busy.

Continue an existing session

Use an existing session when the agent needs earlier findings, messages, or saved work. For example, a session planning dinner can keep the restaurant preferences and results from earlier availability checks.

Here’s how to check for restaurant reservations every two hours in that session:

Check restaurant reservations
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="periodic",
    name="Check restaurant reservations",
    expression="0 */2 * * *",
    timezone="America/New_York",
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Check restaurant availability for our dinner plans. "
            "Compare with earlier checks and report newly available tables."
        ),
    },
)
print(automation.to_json())

Each invocation delivers the saved instructions as an automation notification to the same session, using its current agent configuration and saved state. The notification is separate from a new user message.

If the session is working, delivery waits for it to become available. A scheduled run doesn’t interrupt the active turn or supply a missing tool result or approval. Your application must still handle required actions.

Schedule one check

For a single follow-up, use type: "once" with run_at. The value must be an integer Unix timestamp in seconds that is in the future. Don’t include expression or timezone.

Schedule a check at January 1, 2027, at 9 AM UTC:

Schedule an agent to run once
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="once",
    name="Check restaurant reply",
    run_at=1798794000,
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Check whether the restaurant replied about our booking. "
            "Summarize any changes to the dinner plans."
        ),
    },
)
print(automation.to_json())

A completed one-time schedule has no more scheduled runs. You can still invoke it manually or create another automation for another scheduled follow-up.

Let the agent schedule follow-ups

Add automations to the agent’s tools so it can schedule work requested by the user. This example also enables subagents, so the main agent can delegate each scheduled task and keep a concise summary of the result:

Let agents schedule tasks
from openai import OpenAI

client = OpenAI()
session = client.beta.agents.sessions.create(
    agent={
        "model": "gpt-6-astra",
        "instructions": (
            "Use automations to schedule tasks requested by the user. "
            "Delegate each scheduled task to a subagent and ask for a concise result. "
            "Keep the goal, schedule, and useful summaries in the main session. "
            "Adjust or stop schedules when the user asks."
        ),
        "multi_agent": {"enabled": True},
        "tools": [{"type": "automations"}],
    },
    environment={"type": "openai_hosted"},
    input=(
        "Every day at 10 AM in America/New_York, review the goals we discuss here "
        "and suggest the next actions I could take."
    ),
)
print(session.id)

This lets the agent create, list, get, update, pause, resume, and delete its own automations. The Agents API sets the current session as the target. The agent can create one-time or periodic runs, but it can’t use these tools to start a new session or manage another session’s automations.

The tools can access only automations created by the agent in the current session. Your application can manage those automations through the API, alongside automations it created itself. The Agents API records the creator in created_by; don’t send that field in a create request.

The tool is absent by default. Your application can schedule work without enabling it. Removing the tool from an agent’s configuration doesn’t delete saved schedules; pause or delete them through the API when needed.

Keep repeated work out of the main context

For ongoing goals, enable multi-agent orchestration with agent.multi_agent.enabled: true. Ask the main agent to keep the goal and schedule, delegate each task to a subagent, and retain a short result. This keeps detailed tool output from repeated checks out of the main session’s context window.

For example, include this in the main agent’s instructions:

Delegate each scheduled task to a subagent. Give it the goal and relevant prior findings, and ask for a concise result. Review that result, keep the useful summary, and decide whether to continue, change, or stop the schedule.

The automations tool manages schedules. Keep the other tools and data access the agent needs to do the scheduled work.

Schedule onboarding follow-ups from your app

Your application can also create schedules in response to its own events. For example, when a user signs up, start an onboarding session and schedule its first follow-up for 48 hours later:

Schedule an onboarding follow-up
import time

from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.create(
    type="once",
    name="Onboarding follow-up",
    run_at=int(time.time()) + 48 * 60 * 60,
    target={
        "type": "existing_session",
        "session_id": "sess_123",
        "instructions": (
            "Review onboarding progress and send the next onboarding message "
            "if the user has not completed onboarding."
        ),
    },
)
print(automation.to_json())

After each completed follow-up, your application can schedule another one 48 hours later. Stop when onboarding is complete or the user opts out, and delete any pending follow-up. Use one-time schedules for this interval; a cron day-of-month expression doesn’t represent a repeating 48-hour interval across month boundaries.

The onboarding agent needs access to onboarding progress and the application’s messaging tools. Creating the automation schedules the work; it doesn’t send the message immediately.

Try a run and inspect delivery

To test a saved automation immediately, send POST /v1/agents/automations/auto_123/invocations with no request body. A manual invocation doesn’t change the saved schedule or consume a one-time scheduled run. It also works while the schedule is paused.

Save the returned invocation ID. Retrieve it with GET /v1/agents/automations/auto_123/invocations/ainv_123, or list delivery history with GET /v1/agents/automations/auto_123/invocations.

For an overview of past runs, list the automation’s invocations:

Monitor automation invocations
import OpenAI from "openai";

const client = new OpenAI();
for await (const invocation of client.beta.agents.automations.invocations.list(
  "auto_123"
)) {
  console.log(invocation.id, invocation.status, invocation.session_id);
}

The history contains invocations already created, but it does not include every future occurrence. Inspect these fields:

Field What to check
status Starts as queued; becomes completed when delivery succeeds.
session_id The value identifies the session to follow after delivery and can be null before a session is available.
source.type manual for a manual invocation or automation for a scheduled run.
scheduled_at The intended scheduled time, or null for a manual invocation.

A completed delivery doesn’t mean the agent has completed its work. For a new session, it means the session accepted its initial input. For an existing session, it means the session accepted the notification and the request to start work.

Use the invocation’s session_id to follow session events and inspect the turn’s outcome.

The automation schedules the work. Your application displays session output and sends any notifications to the user.

Change or stop a schedule

Retrieve an automation with GET /v1/agents/automations/auto_123. List your project’s automations with GET /v1/agents/automations; add session_id=sess_123 to find automations targeting an existing session.

Update the cron expression to move a recurring check to 11 AM:

Change a schedule
from openai import OpenAI

client = OpenAI()
automation = client.beta.agents.automations.update(
    automation_id="auto_123",
    expression="0 11 * * *",
)
print(automation.to_json())

Omitted fields stay unchanged. A supplied target replaces the whole target, so include all its required fields and retain its type. Update reminder text in target.instructions or initial messages in target.input. An agent-created automation must retain its creator session as the target.

Make changes before the next scheduled time. Updates apply to future invocations; an invocation that is already queued keeps the target and input saved when it was created.

Use the following operations without a request body:

Goal Operation Effect
Pause scheduled work. POST /v1/agents/automations/auto_123/pause Holds pending scheduled deliveries; manual invocation remains available.
Resume scheduled work. POST /v1/agents/automations/auto_123/resume Reactivates the saved schedule.
Remove the schedule. DELETE /v1/agents/automations/auto_123 Prevents future scheduled and manual invocations.

Pausing or deleting an automation doesn’t stop work already accepted by a session or delete the session. A delivery already in progress may still reach its session. To stop current work, cancel its active turn.

If a one-time automation’s scheduled time passes while it is paused, set a new future run_at before resuming. A completed one-time automation can’t be paused or resumed; create another automation for another scheduled follow-up.