DataFast Analytics Skill

Use this skill to call the DataFast API and summarize results for the user.

Quick Workflow

1. Confirm the request type (overview, timeseries, realtime, breakdown, visitor, goals/payments create/delete).
2. Gather required inputs:
   • Date range: startAt and endAt together or neither (overview/timeseries support ranges).
   • timezone, fields, interval, limit, offset, and any filter_* parameters.
3. Build the HTTP request with Authorization: Bearer $DATAFAST_API_KEY and Content-Type: application/json.
4. Execute with curl and parse JSON.
5. Summarize results in a table plus a short narrative (totals + key takeaways). Include pagination info if relevant.

Setup

1. Get your API key from DataFast (starts with df_).
2. Store it:

mkdir -p ~/.config/datafast
echo "df_your_key_here" > ~/.config/datafast/api_key

Authentication

All requests need:

DATAFAST_API_KEY=$(cat ~/.config/datafast/api_key)
curl ... \
  -H "Authorization: Bearer $DATAFAST_API_KEY" \
  -H "Content-Type: application/json"

If the user hasn't set up the API key, ask them to follow the setup steps above.

Base URL

https://datafa.st/api/v1/

Reference Docs

Use the full API reference at {baseDir}/references/datafast-api-docs.md for endpoint details, response fields, and examples.

Endpoint Guidance

Overview

• GET /analytics/overview
• Optional: startAt, endAt, timezone, fields.

Time Series

• GET /analytics/timeseries
• Typical params: fields, interval (hour/day/week/month), startAt, endAt, timezone, limit, offset.
• Accepts filter_* query params for segmentation.
• Note: fields is required (e.g., fields=visitors,sessions).

Realtime

• GET /analytics/realtime
• GET /analytics/realtime/map

Breakdowns

• GET /analytics/devices
• GET /analytics/pages
• GET /analytics/campaigns
• GET /analytics/goals
• GET /analytics/referrers
• GET /analytics/countries
• GET /analytics/regions
• GET /analytics/cities
• GET /analytics/browsers
• GET /analytics/operating-systems
• GET /analytics/hostnames

Visitor Details

• GET /visitors/{datafast_visitor_id}

Goals

• Create goal: POST /goals
• Delete goals: DELETE /goals (requires at least one filter or time range; confirm scope)

Payments

• Create payment: POST /payments
• Delete payments: DELETE /payments (confirm scope)

Destructive Actions

For DELETE /goals or DELETE /payments:

• Always confirm exact filters and time range in plain English before executing.
• If user asks for "all time" deletion, ask for explicit confirmation.
• Echo the final URL that will be called (without the API key).

Filter Syntax

Use filter_* params for segmentation (e.g., filter_referrer=is:X).

Important: Filter values must match the exact names from breakdown endpoints. For example, X/Twitter is stored as "X" (not "x.com" or "twitter.com"). When in doubt, query the breakdown first:

curl ... "/analytics/referrers?limit=20"

Then use the exact referrer value in your filter.

Example Command Patterns

GET

DATAFAST_API_KEY=$(cat ~/.config/datafast/api_key)
curl -sS "https://datafa.st/api/v1/analytics/overview?startAt=2024-01-01&endAt=2024-01-31&timezone=UTC" \
  -H "Authorization: Bearer $DATAFAST_API_KEY" \
  -H "Content-Type: application/json"

POST

DATAFAST_API_KEY=$(cat ~/.config/datafast/api_key)
curl -sS "https://datafa.st/api/v1/goals" \
  -H "Authorization: Bearer $DATAFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datafast_visitor_id":"...","name":"newsletter_signup","metadata":{"email":"..."}}'

DELETE

DATAFAST_API_KEY=$(cat ~/.config/datafast/api_key)
curl -sS -X DELETE "https://datafa.st/api/v1/goals?name=signup&startAt=2023-01-01T00:00:00Z&endAt=2023-01-31T23:59:59Z" \
  -H "Authorization: Bearer $DATAFAST_API_KEY"

Output Expectations

• Provide a short summary and a flat table of results.
• Include totals and conversion/revenue metrics when present.
• For time series, include the top-level totals and the first/last timestamps in the selected range.
• If pagination exists, report limit, offset, and total, and ask if the user wants the next page.