> ## 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. # Ingest events > Send analytics events to Formo. This endpoint runs on events.formo.so (not api.formo.so). Authenticate with your project's SDK write key. ## OpenAPI ````yaml /api/openapi.json 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. ````