Quick-Start Guide — Your First API Call in 5 Minutes
Quick-Start Guide — Your First API Call in 5 Minutes
This guide gets you from zero to pulling demo analytics data in under 5 minutes. No coding experience required — just a terminal or any HTTP tool (Postman, Insomnia, etc.).
What You Need to Know
- Your API key (provided by your Walnut account team, starts with
wlt_) - A terminal (Mac/Linux) or Postman (Windows/Mac/Linux)
Step 1: Verify the Connection
Run this command — no API key needed. If you get {"status": "ok"}, you're good to go.
curl <https://customer-api.teamwalnut.com/health>
Expected response:
{ "status": "ok" }
Step 2: Pull Your First 5 Sessions
Replace YOUR_API_KEY with the key your Walnut team provided.
curl -H "x-api-key: YOUR_API_KEY" \\
"<https://customer-api.teamwalnut.com/demo-sessions?limit=5>"
What you'll see: A JSON response with your 5 most recent demo sessions, including viewer type, engagement metrics, geography, and more.
Step 3: Filter to What Matters
You probably don't need all 29 fields. Here's how to get just the essentials for external prospects in the last 30 days:
curl -H "x-api-key: YOUR_API_KEY" \\
"<https://customer-api.teamwalnut.com/demo-sessions?fields=demo_name,started_at,is_completed,interaction_count,geo_country_name&user_type=external&start_date=2026-02-01&limit=20>"
This returns only 5 fields instead of 29, filtered to external viewers, scoped to a date range.
Useful filters:
| Filter | Example | What It Does |
|---|---|---|
start_date / end_date | start_date=2026-01-01 | Scope to a date range |
user_type | user_type=external | Only prospects (exclude internal team views) |
demo_id | demo_id=YOUR_DEMO_UUID | Sessions for one specific demo |
fields | fields=demo_name,started_at | Return only the columns you need |
limit | limit=100 | Control how many rows come back (max 10,000) |
Step 4: Get a High-Level Summary
Don't need individual sessions? Get a full analytics snapshot in one call:
curl -H "x-api-key: YOUR_API_KEY" \\
"<https://customer-api.teamwalnut.com/demo-sessions/summary>"
This gives you in a single response:
- Total sessions, completed, and bounced counts
- Average duration, interactions, and screen views
- Breakdown by user type (external vs. internal)
- Breakdown by viewer type (prospect, owner, colleague)
- Embedded vs. direct link split
- Top 10 demos by session volume
- Top 10 countries
You can scope the summary to a specific period:
curl -H "x-api-key: YOUR_API_KEY" \\
"<https://customer-api.teamwalnut.com/demo-sessions/summary?start_date=2026-01-01&end_date=2026-01-31>"
Step 5: See Trends Over Time
Use group_by to aggregate sessions by date — perfect for charts and dashboards:
curl -H "x-api-key: YOUR_API_KEY" \\
"<https://customer-api.teamwalnut.com/demo-sessions?group_by=date&start_date=2026-02-01&user_type=external>"
Response:
{
"data": {
"2026-02-01": 142,
"2026-02-02": 98,
"2026-02-03": 215
},
"total": 455,
"group_by": ["date"]
}
You can also group by user_type, viewer_type, demo_id, or is_embed. Combine multiple dimensions with commas: group_by=date,user_type.
You're Up and Running
That's it — you're pulling live demo analytics data. Here's what to explore next:
| Want to... | Do this |
|---|---|
| Understand every available field | See the full Developer Documentation for all 29 fields with definitions |
| Page through large datasets | Use offset parameter — increment by your limit value until you get fewer rows than requested |
| Build a daily CRM sync | Use start_date set to yesterday + user_type=external to pull daily prospect sessions |
| Feed data to an LLM / AI tool | Point your MCP client at this API — the structured JSON is ready for AI consumption |
Quick Reference
| Detail | Value |
|---|---|
| Base URL | https://customer-api.teamwalnut.com |
| Auth header | x-api-key: YOUR_API_KEY |
| Rate limit | 50 requests/second (burst up to 100) |
| Max rows per request | 10,000 |
| Default rows per request | 1,000 |
| Sort order | Newest sessions first (by started_at) |
| Date format | YYYY-MM-DD |