> ## Documentation Index > Fetch the complete documentation index at: https://developers.datagrid.com/llms.txt > Use this file to discover all available pages before exploring further. # Create automation > Create a new `runAgent` automation for the specified agent. The automation will fire on the provided cron schedule (in the given IANA timezone) and run the agent with the supplied prompt. Schedules must fire at most once every 15 minutes — finer-grained expressions are rejected with a 400 error. ## OpenAPI ````yaml post /agents/{agent_id}/automations openapi: 3.0.3 info: version: 0.1.1 title: Datagrid API description: Datagrid API servers: - url: https://api.datagrid.com/v1 security: - BearerAuth: [] paths: /agents/{agent_id}/automations: post: tags: - Automations summary: Create automation description: >- Create a new `runAgent` automation for the specified agent. The automation will fire on the provided cron schedule (in the given IANA timezone) and run the agent with the supplied prompt. Schedules must fire at most once every 15 minutes — finer-grained expressions are rejected with a 400 error. operationId: CreateAutomation parameters: - name: agent_id in: path required: true description: The ID of the agent to create the automation for. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAutomationRequest' responses: '201': description: Created automation content: application/json: schema: $ref: '#/components/schemas/Automation' '400': description: >- Bad request. The cron expression is invalid, the timezone is not a valid IANA timezone identifier, or the schedule fires more frequently than once every 15 minutes. '404': description: >- Not found. The specified agent does not exist, or the authenticated API key does not have permission to access it. '429': description: >- Rate limit exceeded. The request has been throttled because the rate limit for this endpoint has been reached. Check the `Retry-After` response header and retry after the specified number of seconds. content: application/json: schema: $ref: '#/components/schemas/RateLimitError' components: schemas: CreateAutomationRequest: type: object required: - name - cron - prompt properties: name: type: string description: Human-readable name for the automation. maxLength: 255 description: type: string description: Optional free-text description of what this automation does. maxLength: 600 nullable: true enabled: type: boolean description: >- Whether the automation should be active immediately after creation. Defaults to `true` when omitted or null. Set to `false` to create the automation in a paused state — it will not fire until explicitly enabled via the Update automation endpoint. nullable: true cron: type: string description: >- Five-field cron expression (minute hour day month day-of-week) controlling when the automation fires. Seconds are not supported. The schedule must fire at most once every 15 minutes — finer-grained expressions are rejected with a 400 error. example: 0 9 * * 1 maxLength: 255 timezone: type: string description: >- IANA timezone identifier in which `cron` is interpreted. Defaults to `"UTC"` when omitted. example: America/New_York nullable: true prompt: type: string description: >- The instruction text sent to the agent each time the automation fires. Supports Markdown. This is the agent's task for the run. Must not be empty or whitespace-only. maxLength: 20000 thread_mode: $ref: '#/components/schemas/AutomationThreadMode' nullable: true destination_type: $ref: '#/components/schemas/AutomationDestinationType' nullable: true destination_id: type: string description: >- The channel ID or user ID for the conversation destination. Required when `destination_type` is `channel` or `user_dm`; omit for `agent_dm`. nullable: true maxLength: 255 output_channel_id: type: string description: >- ID of an additional delivery channel (Slack, Teams, email, etc.) where the agent's output is also delivered after each run. Must be provided together with `output_channel_type` — supplying one without the other is rejected with a 400 error. This is an external transport address, not a Datagrid-owned resource — it's validated against the caller's own connected integrations at delivery time. nullable: true maxLength: 255 output_channel_type: type: string enum: - email - slack - teams - sms description: >- Transport type of `output_channel_id`. One of `"email"`, `"slack"`, `"teams"`, `"sms"`. Must be provided together with `output_channel_id`. nullable: true notification_preference: $ref: '#/components/schemas/AutomationNotificationPreference' nullable: true prompt_file_ids: type: array description: >- IDs of files to attach as context for every run of this automation. Each file must exist and belong to the caller's teamspace, or the request is rejected with a 404 error. Limited to 20 IDs per request. nullable: true maxItems: 20 items: type: string Automation: type: object required: - object - id - name - description - enabled - created_at - cron - timezone - prompt - thread_mode properties: object: type: string enum: - automation description: The object type, always 'automation'. id: type: string description: Unique identifier for the automation. name: type: string description: Human-readable name of the automation. description: type: string description: Optional free-text description of what this automation does. nullable: true enabled: type: boolean description: >- Whether the automation is active. When `false` the cron trigger is paused and no runs are scheduled until it is re-enabled. created_at: type: string format: date-time description: ISO 8601 timestamp of when the automation was created. updated_at: type: string format: date-time description: ISO 8601 timestamp of the last modification. nullable: true cron: type: string description: >- Five-field cron expression controlling when the automation fires (e.g. `"0 9 * * 1"` = every Monday at 09:00). Seconds are not supported. Must have a minimum inter-fire interval of 15 minutes. example: 0 9 * * 1 nullable: true timezone: type: string description: >- IANA timezone identifier in which `cron` is interpreted (e.g. `"America/New_York"`, `"UTC"`). Defaults to `"UTC"` when not provided on create. example: America/New_York nullable: true prompt: type: string description: >- The instruction text sent to the agent each time the automation fires. Supports Markdown. nullable: true thread_mode: $ref: '#/components/schemas/AutomationThreadMode' nullable: true destination_type: $ref: '#/components/schemas/AutomationDestinationType' nullable: true destination_id: type: string description: >- The channel ID or user ID that identifies the destination. Required when `destination_type` is `channel` or `user_dm`; omit for `agent_dm`. nullable: true output_channel_id: type: string description: >- ID of an additional delivery channel (Slack channel, Teams channel, email address, etc.) where automation results are also posted. nullable: true output_channel_type: type: string description: >- The transport type of the output channel. One of `"email"`, `"slack"`, `"teams"`, `"sms"`. nullable: true notification_preference: $ref: '#/components/schemas/AutomationNotificationPreference' nullable: true prompt_file_ids: type: array description: >- IDs of files attached to the automation prompt. These files are provided as context to the agent on every run. nullable: true items: type: string RateLimitError: type: object description: >- Returned when the rate limit is exceeded. Rate limits are enforced per teamspace, endpoint path, and HTTP method over a 60-second sliding window. Each endpoint may have its own limit — check the X-RateLimit-Limit response header for the effective value. required: - error - message - retryable - status_code properties: status_code: type: integer description: The HTTP status code (429). statusCode: type: integer deprecated: true description: Deprecated. Use status_code instead. error: type: string enum: - rate_limit_exceeded description: The error code identifying this as a rate limit error. message: type: string description: A human-readable error message. mitigation: type: string description: Suggested action to resolve the error. retryable: type: boolean description: Whether the request can be retried after a delay. details: type: object properties: reason: type: string description: A detailed explanation of why the rate limit was exceeded. AutomationThreadMode: type: string enum: - new_thread - same_conversation description: >- Controls whether each scheduled run creates a fresh conversation thread or continues in the same persistent conversation. - `new_thread` — (default) Each run starts a new conversation. Results are isolated; the agent has no memory of prior runs unless it uses agent memory tools. - `same_conversation` — Every run appends to the same conversation thread. The agent sees the full history of prior runs, which is useful for incremental summaries or stateful workflows. AutomationDestinationType: type: string enum: - agent_dm - channel - user_dm description: |- Where the automation's conversation runs and results are delivered. - `agent_dm` — (default) Results are posted in the agent's own DM space. No `destination_id` is required. - `channel` — Results are posted in a specific Datagrid channel. Provide the channel ID in `destination_id`. - `user_dm` — Results are sent as a direct message to a specific user. Provide the user ID in `destination_id`. AutomationNotificationPreference: type: string enum: - always - on_failure - never description: >- Controls when users are notified about automation run outcomes. - `always` — Notify after every run regardless of success or failure. - `on_failure` — (default) Notify only when a run fails or produces an error. - `never` — Do not send notifications for this automation. securitySchemes: BearerAuth: type: http scheme: bearer ````