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

# Prime functions

> Run a script your account's agent wrote on a schedule, when a platform event happens, or when another system calls a webhook, with no model call, after a person has reviewed the code and an administrator has approved where and when it runs.

> [!NOTE]
>
> Prime functions are not available yet. This page describes how they will work, so
> you can plan for them. Until they are on for your account, `search` and `get` do
> not list the `prime_function` and `function_run` kinds, and `save_prime_function`
> is refused with `FEATURE_NOT_ENABLED`.

Your account's own agent, the Prime (see [hosted buyer agents](https://docs.apostra.com/v3/hosted-buyer-agents.md)),
can write code: a script that pulls a week of delivery into a summary, or checks
pacing across a set of campaigns. A **Prime function** keeps that script and runs it
again later, on a schedule, when a platform event happens, or when another system
calls a webhook. The script runs without the agent: no model call, the same code
every time.

Nothing runs until two people have said yes. A person reads the script and makes it
Live in your Library. An administrator approves where, when and for whom it runs.

## How a function is made

1. **The agent writes the script.** In a conversation you started, the agent saves
   it to your Library as a Draft, in the `script` category. A script is one Python 3
   file.
2. **A person makes it Live.** Anyone with write access to the account and to the
   advertisers the script is filed under can read it and make it Live, as with any
   Draft in your Library. No agent can make a script Live.
3. **The agent proposes the function.** It names the script revision, what starts
   a run, the advertiser or Project it works for, and the one kind of memory it may
   save. You, the person in the conversation, become accountable for its runs. The
   answer is `approval_required`, with a link.
4. **An administrator approves it on Apostra.** The approval page shows the whole
   script, a fingerprint of it (its sha256), what starts a run, the advertisers and
   Project, who is accountable, where each run posts, and a plain list of what the
   script may read. Only an administrator of the account, or of its organization,
   signed in as themselves, can approve, and only for advertisers they can read.

A function is pinned to the exact revision that was approved. If someone saves a
new revision of the script, the function keeps running the old one until a new
version of the function pinning the new revision is approved. If the approved
revision is archived or changed, the function stops.

## What starts a run

Each function has one of these:

| Trigger | When it runs |
| - | - |
| Schedule | On a cron expression with a timezone, every so many minutes, or once at a set time. At most every 15 minutes. |
| Platform event | When one of up to 10 named platform events happens for an advertiser the function works for, such as a creative being rejected. |
| Webhook | When another system, such as your measurement vendor, calls the function's own address with a signed request. |

A canvas on the function's Project or advertiser can also show its latest result
straight away and ask for a fresh run. It never waits for the run to finish.

## What a run can do

A run acts as your account's agent, working for the accountable person. It can
only read, and only the advertisers the function was approved for, and only what
that person can still read. It reads the same campaign, media buy, creative,
delivery and memory information a canvas can.

It writes two things and nothing else:

* **One post** in your account's conversation, or the Project's, saying what ran,
  how it ended, and what the script printed. Only people who can read every
  advertiser the run worked for see it.
* **Up to 20 memories** of the one kind the function was approved for, facts or
  events, in its advertiser's or Project's memory (see [agent memory](https://docs.apostra.com/v3/agent-memory.md)).
  Each is marked as unattended work, so you can see what it saved and forget
  anything you disagree with.

A run never buys, changes a campaign or a media buy, sends a message, saves to the
Library, writes account or personal memory, or writes an instruction. The script
has no passwords or keys, and it cannot reach the internet: it can only call
Apostra's own read proxy.

## Limits

* A run stops after 5 minutes. Up to 8,000 characters of what it prints, and 2,000
  of its errors, are kept.
* A run makes at most 100 reads.
* A function runs at most 12 times an hour, and an account runs at most 2 functions
  at once.
* An account has at most 20 active functions.
* Five failed runs in a row switch a function off. An administrator can switch it
  back on.

Prime functions are not charged while the Prime is in beta.

## Pausing and changing a function

Anyone with write access who can read the function's advertisers can pause it. An
administrator can switch a paused function back on. Changing the script revision,
the trigger, the advertisers, the Project, the accountable person or the memory it
may save makes a new version that needs approval again, and the old version stops
running at once.

If the accountable person leaves your account, their functions pause until a new
version names someone else and is approved.

## For developers

| To | Send |
| - | - |
| List your functions | `search({ kind: "prime_function", filter: { state: "active" } })` |
| Read one | `get({ kind: "prime_function", id })` |
| Pause one | `save_prime_function({ id, state: "paused" })` |
| Switch one back on (administrator) | `save_prime_function({ id, state: "active" })` |
| List a function's runs | `search({ kind: "function_run", filter: { functionId } })` |
| Read one run, with what it printed | `get({ kind: "function_run", id })` |
| Find the memories a function saved | `search({ kind: "agent_record", filter: { functionId } })` |

Hosted orchestrators, external buyer agents and any other agent using its own
credentials can neither propose nor read functions.

### Calling a webhook function

When a webhook function is approved, its address is shown on the function, and its
signing secret is shown once to the approving administrator on Apostra. An
administrator can replace the secret there, and it is shown once again.

Each request is a `POST` with a JSON or plain-text body of at most 64 KB, signed
with HMAC-SHA256 over the Unix timestamp in seconds, a full stop and the raw body:

```
X-Apostra-Signature: t=1763500000,v1=<hex HMAC-SHA256 of "1763500000.<body>">
```

| Answer | Meaning |
| - | - |
| `202` | Accepted. The body carries the run's id. The run happens afterwards. |
| `401` | The address is unknown or the signature is wrong. |
| `409` | The function is not active. |
| `413` | The body is larger than 64 KB. |
| `429` | More than 60 requests in a minute. Retry after the `Retry-After` header. |

A timestamp more than 5 minutes off, or a signature already used, is refused. The
body reaches the script only as data, and is never posted or shown to the agent.

## Related

> [card] [Agent memory](https://docs.apostra.com/v3/agent-memory.md)
>
> Where a function's results are kept

> [card] [Hosted buyer agents](https://docs.apostra.com/v3/hosted-buyer-agents.md)
>
> Your account's own agent and how it runs


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