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.