## Key Concepts

### Two API types
- **Public endpoints** (`/i/v0/e/`, `/batch/`, `/flags`): Use project API key in body. No auth header. No rate limits.
- **Private endpoints** (`/api/projects/:project_id/...`): Use personal API key via `Authorization: Bearer`. Rate limited.

### HogQL Queries
The query endpoint (`POST /api/projects/:project_id/query/`) is the most powerful way to extract data. Uses SQL-like HogQL syntax against tables: `events`, `persons`, `sessions`, `groups`, plus data warehouse tables.

Always include time ranges and LIMIT. Use timestamp-based pagination for large exports.

### Rate Limits (private endpoints)
| Type | Limit |
|------|-------|
| Analytics (insights, persons, recordings) | 240/min, 1200/hr |
| Query endpoint | 2400/hr |
| Feature flag local evaluation | 600/min |
| Other CRUD | 480/min, 4800/hr |

Limits apply per organization. On 429: back off and retry.

### Domains
| Cloud | Public | Private |
|-------|--------|---------|
| US | `us.i.posthog.com` | `us.posthog.com` |
| EU | `eu.i.posthog.com` | `eu.posthog.com` |

### Events API (deprecated)
The `/api/projects/:project_id/events/` endpoint is deprecated. Use HogQL queries or batch exports instead.

## Direct curl

export POSTHOG_API_KEY="phx_..."
   export POSTHOG_PROJECT_ID="12345"
   export POSTHOG_PROJECT_API_KEY="phc_..."  # optional, for capture/flags
   # For EU Cloud:
   # export POSTHOG_HOST="https://eu.posthog.com"
   # export POSTHOG_INGEST_HOST="https://eu.i.posthog.com"

# Capture an event
bash scripts/posthog.sh capture "signup" "user_123" '{"plan":"pro"}'

# Evaluate feature flags
bash scripts/posthog.sh evaluate-flags "user_123"

# HogQL query — top events last 7 days
bash scripts/posthog.sh query "SELECT event, count() FROM events WHERE timestamp >= now() - INTERVAL 7 DAY GROUP BY event ORDER BY count() DESC LIMIT 20"

# List persons
bash scripts/posthog.sh list-persons 10 | jq '.results[] | {name, distinct_ids}'

# List feature flags
bash scripts/posthog.sh list-flags | jq '.results[] | {id, key, active}'

# Create a feature flag
echo '{"key":"new-dashboard","name":"New Dashboard","active":true,"filters":{"groups":[{"rollout_percentage":50}]}}' | \
  bash scripts/posthog.sh create-flag

# List dashboards
bash scripts/posthog.sh list-dashboards | jq '.results[] | {id, name}'

# Private endpoint
curl -H "Authorization: Bearer $POSTHOG_API_KEY" \
  "$POSTHOG_HOST/api/projects/$POSTHOG_PROJECT_ID/feature_flags/"

# HogQL query
curl -H "Authorization: Bearer $POSTHOG_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST -d '{"query":{"kind":"HogQLQuery","query":"SELECT count() FROM events WHERE timestamp >= now() - INTERVAL 1 DAY"}}' \
  "$POSTHOG_HOST/api/projects/$POSTHOG_PROJECT_ID/query/"

# Capture event (public)
curl -H "Content-Type: application/json" \
  -X POST -d '{"api_key":"'$POSTHOG_PROJECT_API_KEY'","event":"test","distinct_id":"u1"}' \
  "$POSTHOG_INGEST_HOST/i/v0/e/"