Getting Started

Send a JSON event, wait a minute, query it with SQL. About 5 minutes end to end.

1. Sign in

Open the TrailStack Console and sign in with GitHub.

2. Create a Space

1. Go to the Spaces page.
2. Click Create.
3. Enter a name (for example, my-app).
4. Click Create space.

Under Advanced options you can set Expiration time (months). Default: no expiration — data is kept indefinitely. Set 1-120 to expire data after that many months.

3. Copy your credentials

On the Space page, find the Connection details section. You will need:

• Inject token — for sending events
• ClickHouse endpoint, database, username, password — for querying

Copy them now — the password is not shown again.

4. Send your first event

Every event needs an event field (string). Add properties as an object:

{"event": "page_view", "properties": {"path": "/pricing", "duration_ms": 3200, "authenticated": true}}

curl

curl -X POST 'https://api.trailstack.io/v1/Spaces/AppendRecords?spaceName=my-app&fireAndForget=false' \
  -H 'Authorization: Bearer <your-inject-token>' \
  -H 'Content-Type: text/plain' \
  -d '{"event": "page_view", "properties": {"path": "/pricing", "duration_ms": 3200, "authenticated": true}}'

JavaScript

const response = await fetch(
  "https://api.trailstack.io/v1/Spaces/AppendRecords?spaceName=my-app&fireAndForget=false",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer <your-inject-token>",
      "Content-Type": "text/plain",
    },
    body: '{"event": "page_view", "properties": {"path": "/pricing", "duration_ms": 3200, "authenticated": true}}',
  },
);

const result = await response.json();
console.log(result);

Python

import requests

response = requests.post(
    "https://api.trailstack.io/v1/Spaces/AppendRecords",
    params={"spaceName": "my-app", "fireAndForget": "false"},
    headers={
        "Authorization": "Bearer <your-inject-token>",
        "Content-Type": "text/plain",
    },
    data='{"event": "page_view", "properties": {"path": "/pricing", "duration_ms": 3200, "authenticated": true}}',
)

print(response.json())

A successful response returns:

{"appendedLines": 1, "appendedBytes": 95}

5. Wait for transformation

Your events flow through three stages before they are queryable:

1. Received — ingested into the input stream
2. Transformed — converted from JSON into typed SQL columns
3. Distributed — written to ClickHouse and ready to query

The Pipeline status section on your Space page shows progress bars for each stage. Transformation typically takes about a minute.

6. Query with SQL

Once all three stages reach 100%, query your data over the ClickHouse HTTP protocol on port 8443:

curl -X POST 'https://api.trailstack.io:8443?database=<your-database>' \
  -u '<your-username>:<your-password>' \
  -d "SELECT * FROM evt_page_view LIMIT 10 FORMAT Pretty"

Your JSON properties are now typed SQL columns. Each event type gets its own view — evt_page_view, evt_signup, etc. The all_events view spans all event types in your Space.

Troubleshooting

• 401 or 403 on ingest — check the Inject token from your Space page.
• Query returns no rows — wait about a minute and retry. Check Pipeline status on your Space page.
• Query auth failure — verify all four ClickHouse credentials are from the same Space.

Next steps

• Ingestion Guide — event contract, batching, schema evolution, error codes
• Connecting Tools — Grafana, DBeaver setup
• AI/MCP Setup — query your data in plain English with Claude or Cursor
• Limits & Plans — free tier, compute units, pricing
• API Reference — full endpoint documentation