> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariacompute.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduled Jobs

> Trigger work every N seconds or at one instant; the cursor advances before execution, ticker is single-flight, and every row is tenant-scoped.

A scheduled job fires at a fixed instant or at a fixed interval. Exactly one of `every_secs` / `at_ms` is required; cron expressions are deliberately unsupported. The ticker advances `next_run_ms` **before** running a job, so a restart or a second replica cannot fire the same instant twice; a one-shot job is disabled after firing.

## Endpoints

```http theme={null}
POST /v1/scheduled-jobs
GET  /v1/scheduled-jobs
DELETE /v1/scheduled-jobs/{job_id}
```

## Authentication

`Authorization: Bearer <api_key>` or `Authorization: ApiKey <key>`. Optional if `AGENT_CLOUD_API_KEY` is unset. Every row is scoped by `principal_id`.

## Request body

**name** `string` *required*

Job name.

**every\_secs** `integer`

Interval in seconds; mutually exclusive with `at_ms`.

**at\_ms** `integer`

Epoch milliseconds for a one-shot trigger (a past instant still fires on the next tick); mutually exclusive with `every_secs`.

**payload** `object`

JSON payload handed to the runtime when the job fires (e.g. `{"prompt": "..."}`).

Supplying neither or both trigger fields returns `400`; deleting another tenant's id returns `403`, an unknown id `404`.

## Response

**id** `string`

Job id (server-generated when omitted).

**object** `string`

Always `scheduled_job`.

**name** `string`

Job name.

**every\_secs** `integer`

Interval in seconds, or `null`.

**at\_ms** `integer`

One-shot trigger instant, or `null`.

**payload** `object`

Trigger payload.

**enabled** `boolean`

Whether the job is active; `false` after a one-shot fires.

**next\_run\_ms** `integer`

Epoch milliseconds of the next fire; `null` when disabled.

```bash cURL theme={null}
curl -X POST https://agent.ariacompute.com/v1/scheduled-jobs \
  -H "Authorization: Bearer $ARIA_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "daily-digest",
    "every_secs": 86400,
    "payload": {"prompt": "Summarise new memories"}
  }'
```

```json 200 theme={null}
{
  "id": "job_01...",
  "object": "scheduled_job",
  "name": "daily-digest",
  "every_secs": 86400,
  "at_ms": null,
  "payload": {"prompt": "Summarise new memories"},
  "enabled": true,
  "next_run_ms": 1740086400000
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.