Skip to main content
POST
Create a monitor

​
Notes

  • To authenticate, you’ll need a Tako API key. It’s best practice to store it as an environment variable to avoid hardcoding sensitive credentials in your code.
  • type is the name of a registered monitor type, and Tako validates parameters against that type’s schema. Call List monitor types first, and build parameters from the type’s parameters_schema.
  • Every channel_ids entry must be a channel you own, so create the channel before the monitor. An id you don’t own returns 404.
  • channel_ids is optional. A monitor with no channels records its firings, and you read them with List a monitor’s firings. To add channels later, call Update a monitor.
  • name is your own label. Tako never fills one in, and never reads it.
  • fire_once defaults to true, which pauses the monitor after its first firing. To fire on every new occurrence, set it to false. A type that reports fire_once_only rejects that.
  • active_from defaults to the moment you create the monitor. active_until must be in the future and after active_from.
  • You can hold a limited number of active monitors. When you’re at that limit, this endpoint returns 400 with error_type: LIMIT_REACHED. See Handle a rejected create.
  • When the monitor fires, Tako posts to every channel you listed. For the request body, the headers, and how to verify the signature, see Webhook deliveries.
A monitor never fires for something that already happened. A firing needs an occurrence that happens after you create the monitor, so you can’t use a monitor to search history. Each type’s lookback_seconds in List monitor types says how far back an occurrence may have happened and still fire, and its description says how long its source takes to report one.

​
Check the resolved subject

The response holds subject: the subject the type matched from your parameters, such as the listing a ticker matched. Read it and confirm the monitor watches what you meant. Tako resolves the subject once, when you create the monitor, and never again. Get a monitor and List monitors return the same subject. parameters comes back in the form this endpoint accepts, with names as Tako resolved them. A ticker you sent as aapl reads back as AAPL, with the exchange that Tako picked.

​
Handle a rejected create

A 400 returns a MonitorCreateRejected with an error_type:
  • AMBIGUOUS_SUBJECT: your parameters match more than one subject. candidates lists every one, best first. Narrow the parameters and retry.
  • LIMIT_REACHED: you’re at your active monitor limit. limit is your cap, and error_message says how to free a slot. Pause or delete a monitor you no longer need, or contact support@tako.com about an enterprise limit.
  • BAD_REQUEST: anything else. candidates is empty and limit is null.
Tako counts the active monitor limit per user, not pooled across an account. A monitor past its active_until doesn’t count against it.

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
type
string
required

A registered monitor type name, domain.subtype, for example stocks.pct_change.

Maximum string length: 64
​
parameters
Parameters · object
required

Tako validates these against the type's parameter schema.

​
name
string
default:""

Your label for the monitor. Tako never fills one in, and never reads it.

Maximum string length: 255
​
fire_once
boolean
default:true

Pause the monitor after its first firing. To fire on every new occurrence, set it to false, which a type that reports fire_once_only rejects.

​
channel_ids
string<uuid>[]

Destinations to post each firing to. Empty means no delivery: the firings are still recorded and readable through listMonitorFirings.

Maximum array length: 20
​
actions
Actions · object[]

What Tako does after the monitor fires, in order. Each entry is an object with kind, that kind's parameters, and optionally channel_ids. channel_ids sets where the action's output goes: leave it out to use the monitor's channels, list channels you own to use those, or send an empty list to keep the output in Tako. Actions aren't available yet, so a non-empty list returns 400.

Maximum array length: 5
​
active_from
string<date-time> | null

Ignore occurrences before this time. Null means from the moment you create the monitor.

​
active_until
string<date-time> | null

Pause the monitor as expired after this time. Null means the monitor has no end. The value must be in the future and after active_from.

Response

The new monitor, in the same shape every later read returns

​
id
string<uuid>
required
​
name
string
required
​
type
string
required
​
parameters
Parameters · object
required

The parameters in the form createMonitor accepts, as this type's parameters_schema describes them. The ids Tako resolved them to never appear here. The names come back as Tako resolved them rather than as you typed them, so a stock monitor created with ticker aapl reads back ticker AAPL and the exchange MIC that resolution picked. A type whose input accepts more than one name for a subject can return a different one than you sent: a crypto monitor names the asset by coinmarketcap_id whichever name you created it with. A monitor Tako can no longer render against its type's current schema returns a reduced form; subject still names what it watches.

​
subject
Subject · object
required

The subject the type resolved from your parameters, such as the listing that a ticker matched, in the shape listMonitorTypes returns as subject_schema. Check it before you rely on the monitor. Tako resolves it once, when you create the monitor, and never re-resolves it, so it names what the monitor watches rather than what that subject is called today. Empty for a type that resolves no subject.

​
fire_once
boolean
required
​
status
enum<string>
required
Available options:
active,
paused
​
status_reason
enum<string> | null
required

Why Tako paused the monitor. Null while the monitor is active, and null when you paused it yourself.

Available options:
fired_once,
unloadable,
expired,
completed
​
active_from
string<date-time> | null
required
​
active_until
string<date-time> | null
required
​
last_evaluated_at
string<date-time> | null
required

When Tako last evaluated this monitor. Null until the first evaluation.

​
last_evaluation_outcome
enum<string> | null
required

How that evaluation ended. Null until the first evaluation, and null again after you resume a paused monitor, because the pause makes the earlier outcome meaningless. On an active monitor with no firings, a recent predates_monitor or before_window means the monitor is running and waiting for an occurrence that happens after you created it. no_occurrence means the type found no occurrence, which includes finding no usable data to compare.

Available options:
fired,
already_fired,
no_occurrence,
predates_monitor,
outside_lookback,
unloadable,
completed,
unknown_type,
inactive,
deleted,
expired,
before_window,
crashed
​
channel_ids
string<uuid>[]
required
​
actions
Actions · object[]
required

The monitor's actions as Tako stored them: the fields you set on each action, and channel_ids only on an action where you set it. A field you left out takes the kind's default when the action runs. Empty for a monitor with no actions.

​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required