Script reference

This page describes what an automation's script can do. In normal use your AI assistant (ChatGPT, Claude, or any other client connected over MCP) writes the script for you, following this reference. You only need it to read a script under Advanced, or to ask for a precise change.

Runtime#

• Language: Python 3.11. Each automation runs on its own, separate from other automations.
• Network and processes: outbound connections only over HTTPS (port 443) to public addresses. No http:// URLs, other ports, raw sockets, UDP or listening sockets, and no subprocess, os.system, multiprocessing or ctypes. A script that does this is rejected before it goes live, and blocked at run time with an error such as "Outbound connections are allowed only over HTTPS (port 443). Port 25 was blocked."
• Entry point: your script is packaged as user_script.py and imported by the ClickRuntime runtime. You only write handlers (see below).
• SDK: import clickruntime (preinstalled).
• Time limit: each run has a time limit (180 seconds by default). Memory is 256 MB by default.
• Secrets and connections: nothing secret is in the environment. The script asks for each one with clickruntime.credentials while it runs (see Secrets and connections).

Handlers#

A script registers handlers with decorators. At least one of @on_trigger or @on_event is required.

The handler's return value (any JSON-serializable value) is stored as the run's result.

from clickruntime import on_trigger, state, log, notify, http, credentials

@on_trigger
def run(event):
    token = credentials.secret("SHOP_TOKEN")
    resp = http.get("https://api.example.com/price", headers={"Authorization": f"Bearer {token}"})
    price = resp.json()["price"]
    last = state.get("last_price")
    state.set("last_price", price)
    if last is not None and price < last:
        notify.email_me("Price dropped", f"Now {price} (was {last})")
    log.info("checked price", {"price": price})
    return {"price": price}

Schedule and manual payloads#

@on_trigger receives:

{"type": "schedule", "scheduled_time": "2026-01-01T09:00:00Z"}

scheduled_time is the UTC time the run was due, not when it started. A manual run receives {"type": "manual"}, possibly with "requested_by": "assistant" | "website". When an assistant asked for the run, "requested_via" names it, such as "ChatGPT" or "Claude Code".

Schedules#

Schedules are stored in plain terms, not cron expressions:

Timezones are IANA names such as America/New_York, and schedules run at that local time, including across daylight saving changes. The shortest interval is 5 minutes; one-minute schedules are not available, and a cron expression must keep its runs at least 5 minutes apart.

Incoming payloads (trigger links)#

@on_event receives an Event built from the request:

{
  "type": "incoming",
  "received_at": "2026-01-01T09:00:00Z",
  "event": {"id": "evt_1", "type": "checkout.session.completed"},
  "headers": {"content-type": "application/json", "stripe-signature": "t=...,v1=..."},
  "raw_body": "{\"id\":\"evt_1\",...}",
  "event_id": "ev_01J...",
  "verified": {"provider": "stripe", "ok": true}
}

Trigger links have the form https://clickruntime.com/in/<key> and accept POST bodies up to 1 MB of UTF-8 text (other encodings get 415 invalid_encoding). A delivery returns 202 {"ok": true, "event_id", "duplicate", "queued"}. A repeated sender delivery id (webhook-id, svix-id, x-github-delivery, x-shopify-webhook-id, or a Stripe evt_ id) returns duplicate: true and does not run the script a second time.

The Event object#

@on_event
def handle(event):
    event.json                          # parsed body
    event.headers                       # dict, lowercase keys
    event.header("Stripe-Signature")    # case-insensitive lookup
    event.body                          # raw body string (alias: event.raw_body)
    event.event_id, event.received_at
    event.verified, event.is_verified   # platform verification result
    event.type                          # "incoming" | "schedule" | "manual"
    event.is_incoming, event.is_schedule, event.is_manual
    event.scheduled_time                # schedule runs only

Event is also a dict, so event["event"] works. event.data is the same as event.json; when the body wasn't parsed, event.json tries to parse raw_body.

Signature verification#

On the platform (recommended)#

On the automation page, under Trigger link, choose the sender (stripe, github, shopify, typeform, standard_webhooks or hmac_sha256), name the secret that holds its signing secret, and turn on Require signature. Your assistant can set the same settings when it builds or changes the automation. Your script sees event.verified ({"provider", "ok"}, or null when no sender is chosen).

With Require signature on, a delivery that fails is answered with 401 invalid_signature, stored as Rejected: signature invalid in the automation's recent events, and never runs. With it off, the delivery runs and event.verified.ok is False. A missing signing secret counts as a failed check. Test events sent from the ClickRuntime dashboard skip verification.

If a sender signs something other than the raw body, such as a timestamp and the body together, verify in the script instead.

In the script#

clickruntime.verify has constant-time helpers. Each returns True or False.

from clickruntime import on_event, verify, credentials

@on_event
def handle(event):
    if not verify.stripe(event.body, event.header("stripe-signature"), credentials.secret("STRIPE_WEBHOOK_SECRET")):
        raise ValueError("bad signature")
    ...

Remembered state#

Values and counters that survive between runs, stored per automation. Clear them from the automation page under Advanced with Clear live state.

Keep state small: last-seen ids, prices, timestamps, counters. It is not a database. Keys are 1–255 characters; each value is JSON up to 1 MB. Values stay until deleted or cleared; each counter bucket expires ttl_days (up to 3650) after its bucket time. query_metric returns a list of {"time", "value"} buckets. Never store keys or tokens in state. For patterns (only new items, alert on change, thresholds, cooldowns), see State between runs.

Secrets and connections#

Nothing secret is in the environment. The script asks for each credential when it needs it, with clickruntime.credentials. Values never appear in the script or in chat.

• Declare every secret and connection the script uses in its setup needs. A credential that isn't declared is refused.
• Call these inside the handler, not at import time: values exist only while the run is running.
• Access tokens are refreshed when needed. Every value is masked in logs, results and errors as soon as it is read.
• Errors raise credentials.CredentialError with a safe message and a .code such as not_declared, connection_missing, connection_needs_reauth, secret_missing or run_not_running. A badly formed name raises ValueError.

Google, for example, is connected through your workspace's own Google app, added with the slug google. It has the scopes you gave that app, such as Sheets (spreadsheets), Gmail (gmail.send, gmail.readonly or gmail.modify) and Calendar (calendar.events). If access is revoked, the connection shows Reconnect on Connections & secrets.

from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build
from clickruntime import credentials

token = credentials.connection("google", "work")
sheets = build("sheets", "v4", credentials=Credentials(token), cache_discovery=False)

Notify#

Both raise ValueError on an empty subject or text, and notify.NotifyError when sending fails. The error message names the reason, for example slack_not_connected, channel_required, run_limit, daily_limit, or a Slack refusal such as channel_not_found or not_in_channel.

AI#

clickruntime.ai calls a language model with no API key. Calls count against the workspace's monthly AI tokens, which every plan includes, including the free plan. Input and output tokens are counted separately.

from clickruntime import ai

r = ai.generate("Classify this email as billing, bug or other:\n" + body[:2000], max_output_tokens=20)
label = r.text.strip()

r = ai.generate(text, system="Extract the order.", json_schema={
    "type": "object",
    "properties": {"order_id": {"type": "string"}, "total": {"type": "number"}},
    "required": ["order_id"],
})
order = r.json

• ai.generate(prompt, *, system=None, max_output_tokens=512, json_schema=None) returns AIResult with text, json (the parsed object when json_schema is given), usage, remaining and finish_reason.
• prompt is a string, an ai.Text, or a list of them. Text only for now.
• The model has no tools and can't fetch URLs: fetch the page with http and pass the text in.
• Prompts and answers are not stored; only token counts are recorded.
• Failures raise a subclass of ai.AIError (with .code): AINotIncluded, AILimitReached (monthly tokens or this run's calls used up), AIRateLimited, AIInputTooLarge or AIUnavailable.

Checks that find nothing new#

A scheduled script that polls a source for new items should call report_fetched(count) once, right after the fetch:

from clickruntime import on_trigger, report_fetched

@on_trigger
def run(event):
    items = fetch_new_items()
    report_fetched(len(items))
    if not items:
        return
    ...

A scheduled run that reports 0, sends no notification and finishes quickly doesn't count toward monthly runs. It still appears in the run history.

HTTP helper#

clickruntime.http wraps requests with safer defaults:

• http.get / post / put / patch / delete / head / request(method, url, **kwargs)
• 20-second default timeout.
• Retries connection errors and 429/502/503/504 responses for GET, HEAD, OPTIONS, PUT and DELETE (not POST or PATCH), honoring Retry-After.
• http.session(timeout=20, retries=3, backoff=0.5) for a reusable session.
• Responses are ordinary requests.Response objects.

Logs#

log.debug / info / warning / error(message, extra=None); log.error(..., exc_info=True) attaches the traceback. print output is captured too. Logs are capped at 4 MB per run (oldest lines dropped first).

Secret values are masked in logs, results and errors, including their base64 and URL-encoded forms and well-known token shapes (for example xoxb-, ghp_, sk_live_, whsec_, AKIA…). Values shorter than 4 characters are not masked. Never print environment variables. To mask a value yourself, for example before returning it, use redact.redact(value) (works on strings, dicts and lists).

Environment variables#

No secrets or tokens are in the environment. The runtime sets these for its own use:

Available packages#

Importable without any install step: requests, httpx, pytz, python-dateutil (dateutil), beautifulsoup4 (bs4), lxml, feedparser, openpyxl, PyYAML (yaml), Jinja2 (jinja2), google-api-python-client (googleapiclient), google-auth (google.auth, google.oauth2), slack_sdk, stripe, twilio, Markdown (markdown), their dependencies, and the Python standard library (except modules that open other kinds of connections or start processes: smtplib, imaplib, poplib, ftplib, telnetlib, socketserver, subprocess, multiprocessing and ctypes). Other PyPI packages can be declared as dependencies of the automation and are installed when it deploys; packages known to be malicious are refused. A script that imports something neither available nor declared is rejected before it can go live.

Limits#

Run statuses#

Retries#

Runs started by an incoming event are retried when the platform fails or the run times out: up to 3 attempts in total, 30 seconds and then 2 minutes apart. The run keeps one id and shows which attempt it is on. Script errors are not retried unless you turn on Also retry script errors under Retries on the automation page (only do that if the script is safe to run twice for the same event; use event.event_id to skip work already done). You can also lower the total to 1 or 2 attempts. Scheduled and manual runs are not retried; the next scheduled run happens as usual.

Retention#

• Incoming events are kept for 30 days, then deleted.
• Run logs are kept for 90 days, then cleared. The run itself (status, times, summary) stays in the run history.
• Each run's outbound connection records (destination host, address, port and counts) are kept for 90 days to investigate abuse.
• Remembered state stays until you clear it or delete the automation.

Error codes#

Errors from the ClickRuntime API and from the assistant's tools come back as {"error": "<code>", "message": "<plain text>"}. The codes you are most likely to see:

The assistant's tools can also return: invalid_argument, invalid_setup_needs, secret_in_argument, is_draft, no_script, no_pending_change, confirmation_required, confirmation_missing, confirmation_used, confirmation_expired, confirmation_stale, arm_failed, disarm_failed and unavailable. These are handled in the chat; the assistant explains what to do.