> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formo.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Track Event
> Send individual or batched events to Formo from any source via the Events API at events.formo.so. Supports custom events and all standard event types.
Send events to Formo from any source. Sending custom events? See the [event specs](/data/events/track).
This endpoint is hosted on `events.formo.so`, a separate service from the main API at `api.formo.so`.
Sending events from the backend? Use the [server-side SDK](https://docs.formo.so/sdks/server).
## OpenAPI
````yaml POST /v0/raw_events
openapi: 3.1.0
info:
title: Formo Public API
description: >-
REST API for managing Formo projects, analytics, alerts, boards, charts,
contracts, segments, and AI chat.
**Auth.** All endpoints require a workspace API key with the appropriate
scopes (see `x-api-scopes`).
**Response shape.** Successful responses return the resource directly (or `{
data: [...], total, page, size, has_more }` for paginated lists). HTTP
status carries success/failure; there is no envelope wrapping success
bodies.
**Errors.** Every non-2xx response uses the `Error` envelope: `{ error: {
code, message, doc_url, param?, details? } }`. Branch on the
machine-readable `code` (see `ErrorCode` enum) and follow `doc_url` to the
matching section of the [errors
reference](https://docs.formo.so/api/errors).
**Idempotency.** Pass an `Idempotency-Key` header on POST/PUT/PATCH/DELETE
to make retries safe; the response is cached for 24 h and replayed on
duplicate keys.
version: 0.1.0
contact:
name: Formo
url: https://formo.so
servers:
- url: https://api.formo.so
description: API Server (boards, alerts, contracts, segments, profiles, query, import)
- url: https://events.formo.so
description: Events Server (event ingestion)
security:
- WorkspaceApiKey: []
tags:
- name: Alerts
description: Manage project alerts and notifications
- name: Boards
description: Manage dashboard boards
- name: Charts
description: Manage charts within boards
- name: Contracts
description: Manage blockchain contract monitoring
- name: Segments
description: Manage user segments
- name: Profiles
description: Wallet profiles and import
- name: Query
description: >-
Execute SQL queries and call pre-built analytics endpoints (KPIs, top
pages, lifecycle, retention, revenue). Requires the query:read scope.
- name: Events
description: Event ingestion API (events.formo.so)
paths:
/v0/raw_events:
post:
tags:
- Events
summary: Ingest events
description: >-
Send analytics events to Formo. This endpoint runs on events.formo.so
(not api.formo.so). Authenticate with your project's SDK write key.
operationId: ingestEvents
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Event'
examples:
pageView:
summary: Track a page view
value:
- type: page
channel: web
version: '1'
anonymous_id: e397c4e7-5f0a-45d6-a06c-f34a809d8b82
user_id: ''
address: ''
event: ''
context:
user_agent: >-
Mozilla/5.0 (Windows NT 10.0; Win64; x64)
AppleWebKit/537.36 (KHTML, like Gecko) Chrome/144.0.0.0
Safari/537.36
locale: en-US
timezone: America/Los_Angeles
location: US
ref: ''
referrer: ''
utm_campaign: ''
utm_content: ''
utm_medium: ''
utm_source: ''
utm_term: ''
page_title: Dashboard | MyApp
page_url: https://myapp.com/swap/ethereum#/swap
page_path: /swap/ethereum
library_name: Formo Web SDK
library_version: 1.27.0
browser: chrome
device: desktop
os: Windows
screen_width: 1280
screen_height: 720
screen_density: 1.5
viewport_width: 1280
viewport_height: 604
properties:
url: https://myapp.com/swap/ethereum#/swap
path: /swap/ethereum
hash: '#/swap'
query: ''
original_timestamp: '2026-04-28T02:08:30.000Z'
sent_at: '2026-04-28T02:09:00.000Z'
message_id: >-
263434374239d12b797bf571c6045d6f9f9000a70f19f94d75ca485536606b27
walletConnect:
summary: Track a wallet connection
value:
- type: connect
channel: web
version: '1'
anonymous_id: 66b81795-cf59-43d1-80ab-ef48098b6e06
user_id: ''
address: '0xA39260F25D6ebBEAE4595977bDE410623A96E7Af'
event: ''
context:
user_agent: >-
Mozilla/5.0 (Windows NT 10.0; Win64; x64)
AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0
Safari/537.36
locale: en-US
timezone: Europe/London
location: GB
page_title: MyApp - Swap & Bridge
page_url: https://myapp.com/earn/positions
library_name: Formo Web SDK
library_version: 1.27.0
browser: chrome
device: desktop
os: Windows
properties:
rdns: io.metamask
chain_id: 43114
provider_name: MetaMask
original_timestamp: '2026-04-27T20:04:54.000Z'
sent_at: '2026-04-27T20:05:00.000Z'
message_id: >-
b0a1dc19c494df191e2cb0c56460f7472113e5858440b3d4f3798a070265f631
trackEvent:
summary: Track a custom event
value:
- type: track
channel: web
version: '1'
anonymous_id: 66b81795-cf59-43d1-80ab-ef48098b6e06
address: '0xA39260F25D6ebBEAE4595977bDE410623A96E7Af'
event: Chain Switched
context:
user_agent: >-
Mozilla/5.0 (Windows NT 10.0; Win64; x64)
AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0
Safari/537.36
locale: en-US
timezone: Europe/London
location: GB
page_url: https://myapp.com/swap
library_name: Formo Web SDK
library_version: 1.27.0
browser: chrome
device: desktop
os: Windows
properties:
old_network: Arbitrum
new_network: BNB Chain
original_timestamp: '2026-04-27T23:05:38.000Z'
sent_at: '2026-04-27T23:05:42.000Z'
message_id: >-
f4b2e8c1a59d3e7f6c8b9a02d5e4f1c3b8a7e6d5c4b3a291807e6d5c4b3a2918
identify:
summary: Identify a wallet
value:
- type: identify
channel: web
version: '1'
anonymous_id: 66b81795-cf59-43d1-80ab-ef48098b6e06
user_id: usr_42a91c2b
address: '0xA39260F25D6ebBEAE4595977bDE410623A96E7Af'
event: null
context:
library_name: Formo Web SDK
library_version: 1.27.0
user_agent: >-
Mozilla/5.0 (Windows NT 10.0; Win64; x64)
AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0
Safari/537.36
locale: en-US
timezone: Europe/London
location: GB
page_url: https://myapp.com/dashboard
browser: chrome
device: desktop
os: Windows
properties:
rdns: io.metamask
provider_name: MetaMask
email: alice@example.com
display_name: alice.eth
original_timestamp: '2026-04-27T20:05:10.000Z'
sent_at: '2026-04-27T20:05:11.000Z'
message_id: >-
7e2a4b1c8d3f6e9a0b5c2d1e4f7a8b6c9d0e3f2a1b4c5d6e7f8a9b0c1d2e3f4a
transaction:
summary: Track an onchain transaction
value:
- type: transaction
channel: web
version: '1'
anonymous_id: 66b81795-cf59-43d1-80ab-ef48098b6e06
user_id: ''
address: '0xA39260F25D6ebBEAE4595977bDE410623A96E7Af'
event: ''
context:
library_name: Formo Web SDK
library_version: 1.27.0
user_agent: >-
Mozilla/5.0 (Windows NT 10.0; Win64; x64)
AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0
Safari/537.36
locale: en-US
timezone: Europe/London
location: GB
page_url: https://myapp.com/swap
browser: chrome
device: desktop
os: Windows
properties:
status: confirmed
chain_id: 1
to: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
value: '0'
transaction_hash: >-
0x6f4c1f2c3a8b9e0d1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e
function_name: transfer
function_args:
to: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'
amount: '1000000000'
revenue: 250.5
currency: usd
original_timestamp: '2026-04-27T22:14:03.000Z'
sent_at: '2026-04-27T22:14:04.000Z'
message_id: >-
a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2
responses:
'200':
description: Events ingested
content:
application/json:
schema:
type: object
properties:
successful_rows:
type: integer
quarantined_rows:
type: integer
example:
successful_rows: 1
quarantined_rows: 0
security:
- WorkspaceApiKey: []
servers:
- url: https://events.formo.so
components:
schemas:
Event:
type: object
description: A single analytics event
required:
- type
- anonymous_id
- version
- channel
- message_id
properties:
type:
type: string
enum:
- page
- connect
- disconnect
- chain
- signature
- transaction
- track
- decoded_log
- detect
- identify
channel:
type: string
enum:
- web
- mobile
- server
- api
- import
description: >-
Source of the event. The Formo Web SDK uses `web`; mobile SDK uses
`mobile`; server SDK uses `server`. Use `api` for direct HTTP
submissions and `import` for backfills.
version:
type: string
description: SDK schema version. Web SDK 1.x emits `1`; legacy clients emit `0`.
example: '1'
anonymous_id:
type: string
description: Anonymous visitor identifier
user_id:
type: string
nullable: true
description: Identified user ID
address:
type: string
nullable: true
description: Wallet address
event:
type: string
nullable: true
description: Event name (for track events)
context:
$ref: '#/components/schemas/EventContext'
properties:
$ref: '#/components/schemas/EventProperties'
original_timestamp:
type: string
format: date-time
sent_at:
type: string
format: date-time
message_id:
type: string
description: Unique ID for deduplication
EventContext:
type: object
description: Contextual information about the event environment
properties:
user_agent:
type: string
locale:
type: string
description: e.g. en-US
timezone:
type: string
description: e.g. America/New_York
page_url:
type: string
page_path:
type: string
page_title:
type: string
page_query:
type: string
page_hash:
type: string
referrer_url:
type: string
referrer:
type: string
ref:
type: string
utm_source:
type: string
utm_medium:
type: string
utm_campaign:
type: string
utm_term:
type: string
utm_content:
type: string
browser:
type: string
device:
type: string
enum:
- desktop
- mobile
- tablet
os:
type: string
screen_width:
type: integer
screen_height:
type: integer
screen_density:
type: number
description: Pixel density of the device screen (devicePixelRatio)
viewport_width:
type: integer
description: Width of the browser viewport in pixels
viewport_height:
type: integer
description: Height of the browser viewport in pixels
location:
type: string
description: Geographic location country code (e.g., US, NG)
library_name:
type: string
library_version:
type: string
EventProperties:
type: object
description: >-
Event-specific properties. Can contain any key-value pairs relevant to
the event.
additionalProperties: true
securitySchemes:
WorkspaceApiKey:
type: http
scheme: bearer
description: >-
Workspace API key (e.g. `formo_xxx`). Create one in the Formo dashboard
under Team Settings > API Keys.
````