---
title: "Create a synthetic"
method: POST
path: "/api/{org_id}/synthetics"
tags: ["Synthetics"]
---

# Create a synthetic

`POST /api/{org_id}/synthetics`

## Request

- Base URL: `https://api.openobserve.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.openobserve.ai/api/{org_id}/synthetics`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/openobserve/apis/openobserve-api-http/docs/api/:org_id/synthetics/post.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `org_id` string, required

## Query parameters

- `folder` string

## Request body

- Synthetic
  - `alert_if_fails` integer: Alert only after this many consecutive failures (like alerts trigger_tolerance).
  - `auth` union
    - object
      - `password` string, required
      - `type` 'basic', required
      - `username` string, required
    - object
      - `token` string, required
      - `type` 'bearer', required
    - object: Reference to a secret stored in OO secrets manager.
      - `secret_name` string, required
      - `type` 'secret', required
  - `collect_rum_data` boolean: Collect RUM data for browser checks (session replay / performance).
  - `config` unknown, required
  - `cookies` SyntheticCookie[]: Cookies injected into the browser context before any steps run. Orthogonal to auth — can be combined with basic/bearer auth.
    - `domain` string, required
    - `http_only` boolean
    - `name` string, required
    - `path` string
    - `secure` boolean
    - `value` string, required: Cookie value — encrypted at rest with org DEK.
  - `cooldown_mins` integer: Silence period (minutes) between repeated alert notifications.
  - `created_at` integer
  - `description` string
  - `destinations` string[]: Alert destination names to notify on check failure.
  - `enabled` boolean, required
  - `environments` string[]: Environments this check runs against, by id.
  - `folder_id` string: Folder this synthetic belongs to, as the public folder slug the API accepts and returns; it is resolved to the `folders.id` KSUID on write.
  - `frequency` SyntheticFrequency, required
    - `cron` string
    - `interval` integer
    - `timezone` string, nullable: IANA timezone name (e.g. "America/New_York"). Used for cron scheduling and display.
    - `type` 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'cron'
  - `id` string
  - `last_check_status` 'passed' | 'warning' | 'failed' | 'unknown' | 'error'
  - `last_triggered_at` integer: When the scheduler last fanned out this synthetic (microseconds). UI: "LAST CHECK".
  - `locations` string[], required
  - `name` string, required
  - `next_run_at` integer: Pre-computed next fire time (microseconds). 0 = fire on first tick.
  - `org_id` string
  - `owner` string, nullable: Email of the user who created this synthetic. Set on create, never updated.
  - `retries` integer: Number of retries before marking a check failed (0 = no retry).
  - `session_replay` boolean: Enable session replay capture (browser checks only).
  - `start` integer, nullable: Unix epoch microseconds — when to first run the check ("schedule later"). When set, the scheduler uses this as the initial next_run_at instead of firing immediately.
  - `tags` string[]: User-defined tags for filtering/grouping (e.g. ["prod", "checkout"]).
  - `target` string, required: Target URL (HTTP/Browser) or host:port (TCP/TLS/SSH).
  - `template` string, nullable: Template override for this check's messages; null or "" uses the destination's.
  - `type` 'http' | 'tcp' | 'tls' | 'ssh' | 'browser', required
  - `tz_offset` integer: UTC offset in minutes, used only when `frequency.timezone` is absent or unparseable.
  - `updated_at` integer
  - `variables` SyntheticVariable[]: Key-value variables injected into the probe environment.
    - `example` string: Placeholder shown in the UI when secure=true and value is empty/redacted.
    - `name` string, required
    - `secure` boolean: UI display flag: true = mask value as ••••. No effect on storage — all values are AES-encrypted at rest unconditionally.
    - `value` string, required
  - `wait_before_retry_secs` integer: Seconds to wait between retry attempts.

## Response `200`

Created

- Synthetic
  - `alert_if_fails` integer: Alert only after this many consecutive failures (like alerts trigger_tolerance).
  - `auth` union
    - object
      - `password` string, required
      - `type` 'basic', required
      - `username` string, required
    - object
      - `token` string, required
      - `type` 'bearer', required
    - object: Reference to a secret stored in OO secrets manager.
      - `secret_name` string, required
      - `type` 'secret', required
  - `collect_rum_data` boolean: Collect RUM data for browser checks (session replay / performance).
  - `config` unknown, required
  - `cookies` SyntheticCookie[]: Cookies injected into the browser context before any steps run. Orthogonal to auth — can be combined with basic/bearer auth.
    - `domain` string, required
    - `http_only` boolean
    - `name` string, required
    - `path` string
    - `secure` boolean
    - `value` string, required: Cookie value — encrypted at rest with org DEK.
  - `cooldown_mins` integer: Silence period (minutes) between repeated alert notifications.
  - `created_at` integer
  - `description` string
  - `destinations` string[]: Alert destination names to notify on check failure.
  - `enabled` boolean, required
  - `environments` string[]: Environments this check runs against, by id.
  - `folder_id` string: Folder this synthetic belongs to, as the public folder slug the API accepts and returns; it is resolved to the `folders.id` KSUID on write.
  - `frequency` SyntheticFrequency, required
    - `cron` string
    - `interval` integer
    - `timezone` string, nullable: IANA timezone name (e.g. "America/New_York"). Used for cron scheduling and display.
    - `type` 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'cron'
  - `id` string
  - `last_check_status` 'passed' | 'warning' | 'failed' | 'unknown' | 'error'
  - `last_triggered_at` integer: When the scheduler last fanned out this synthetic (microseconds). UI: "LAST CHECK".
  - `locations` string[], required
  - `name` string, required
  - `next_run_at` integer: Pre-computed next fire time (microseconds). 0 = fire on first tick.
  - `org_id` string
  - `owner` string, nullable: Email of the user who created this synthetic. Set on create, never updated.
  - `retries` integer: Number of retries before marking a check failed (0 = no retry).
  - `session_replay` boolean: Enable session replay capture (browser checks only).
  - `start` integer, nullable: Unix epoch microseconds — when to first run the check ("schedule later"). When set, the scheduler uses this as the initial next_run_at instead of firing immediately.
  - `tags` string[]: User-defined tags for filtering/grouping (e.g. ["prod", "checkout"]).
  - `target` string, required: Target URL (HTTP/Browser) or host:port (TCP/TLS/SSH).
  - `template` string, nullable: Template override for this check's messages; null or "" uses the destination's.
  - `type` 'http' | 'tcp' | 'tls' | 'ssh' | 'browser', required
  - `tz_offset` integer: UTC offset in minutes, used only when `frequency.timezone` is absent or unparseable.
  - `updated_at` integer
  - `variables` SyntheticVariable[]: Key-value variables injected into the probe environment.
    - `example` string: Placeholder shown in the UI when secure=true and value is empty/redacted.
    - `name` string, required
    - `secure` boolean: UI display flag: true = mask value as ••••. No effect on storage — all values are AES-encrypted at rest unconditionally.
    - `value` string, required
  - `wait_before_retry_secs` integer: Seconds to wait between retry attempts.

## Other responses

- `500`: Error

---

[API](https://skmtc.dev/openobserve/apis/openobserve-api-http.md) - [All operations](https://skmtc.dev/openobserve/apis/openobserve-api-http/llms.txt) - [OpenAPI document](https://skmtc.dev/openobserve/apis/openobserve-api-http/revisions/0529b8a10252?raw)