---
title: "Quick-Start Guide — Your First API Call in 5 Minutes"
slug: "/help/api/quick-start"
sidebar_position: 3
last_updated: "2026-03-10T11:56:57Z"
zendesk_id: 49764014048275
zendesk_url: "https://help.walnut.io/hc/en-us/articles/49764014048275-Quick-Start-Guide-Your-First-API-Call-in-5-Minutes"
locale: "en-us"
product: "api"
displayed_sidebar: "apiSidebar"
---

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](https://www.postman.com/) (Windows/Mac/Linux)

<aside>

🔑

**Keep your API key safe.** Treat it like a password. Don't share it in Slack, email, or commit it to code repositories. If you lose it, contact your Walnut account team for a replacement.

</aside>

---

## Step 1: Verify the Connection

Run this command — no API key needed. If you get `{"status": "ok"}`, you're good to go.

```bash
curl <https://customer-api.teamwalnut.com/health>
```

**Expected response:**

```json
{ "status": "ok" }
```

---

## Step 2: Pull Your First 5 Sessions

Replace `YOUR_API_KEY` with the key your Walnut team provided.

```bash
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.

<aside>

✅

**Got data back?** You're authenticated and connected. Everything below builds on this.

</aside>

<aside>

❌

**Got an error?**

-   `401 Unauthorized` → Check that you included the `x-api-key` header (not `Authorization`)
-   `403 Forbidden` → Double-check your API key is correct and active
-   Connection error → Make sure you can reach `customer-api.teamwalnut.com` from your network

</aside>

---

## 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**:

```bash
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:

```bash
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:

```bash
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:

```bash
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:**

```json
{
  "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` |

<aside>

💬

**Need help?** Reach out to your Walnut account team with the request URL, timestamp, and HTTP status code — we'll sort it out quickly.

</aside>