🎁 Get the FREE AI Skills Starter Guide — Subscribe →
BytesAgainBytesAgain
BytesAgain › Skills › Flowsery
🦀 ClawHub

Flowsery

by @tarasshyn

Query web analytics data from Flowsery Analytics — a privacy-first web analytics platform. Retrieve real-time visitors, time series, breakdowns (device, page...

Versionv1.0.4
Downloads534
#database#security#data#legal
TERMINAL
clawhub install flowsery

📖 About This Skill

name: flowsery description: Query web analytics data from Flowsery Analytics — a privacy-first web analytics platform. Retrieve real-time visitors, time series, breakdowns (device, page, country, referrer, campaign, channel, exit link, and 24 dimensions total), visitor profiles with activity timelines, and track/manage custom goals and revenue attribution. Use when the user wants to check their website traffic, analyze visitor behavior, view revenue data, track conversions, or query any analytics metric from their Flowsery-tracked sites. homepage: https://flowsery.com metadata: { 'openclaw': { 'emoji': '📊', 'primaryEnv': 'FLOWSERY_API_KEY', 'requires': { 'env': ['FLOWSERY_API_KEY'] } } }

Flowsery Analytics

Privacy-first web analytics. Query real-time visitors, breakdowns, time series, revenue, goals, and visitor profiles — all via one API.

Setup

1. Sign up at https://flowsery.com/signup 2. Add your website and install the tracking snippet 3. Go to Site Settings → API tab → generate an API key 4. Set the environment variable: 

   export FLOWSERY_API_KEY="flow_sk_live_your-token-here"

Base URL: https://analytics.flowsery.com/api/v1 Auth header: Authorization: Bearer $FLOWSERY_API_KEY

All API keys use the flow_ prefix (e.g. flow_sk_live_abc123). Treat them like passwords — never expose in client-side code.

Core Workflow

1. Check website metadata

curl -s -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  https://analytics.flowsery.com/api/v1/metadata

Returns { "status": "success", "data": [{ "domain", "timezone", "name", "logo", "kpiColorScheme", "kpi", "currency" }] }. Use the timezone and currency values for subsequent queries.

2. Get site overview (aggregated metrics)

curl -s -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  "https://analytics.flowsery.com/api/v1/overview?startAt=2026-01-01&endAt=2026-01-31&timezone=America/New_York"

Returns: visitors, sessions, bounce_rate, avg_session_duration, revenue, revenue_per_visitor, conversion_rate.

Omit date params for all-time data. Use fields param to select specific metrics: ?fields=visitors,revenue.

3. Get time series data

curl -s -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  "https://analytics.flowsery.com/api/v1/timeseries?interval=day&fields=visitors,sessions,revenue&startAt=2026-03-01&endAt=2026-03-31"

Intervals: hour, day, week, month. Returns timestamped data buckets with totals.

Response includes data array, totals object (with visitors, sessions, revenue, revenueBreakdown), and pagination.

4. Check real-time visitors

curl -s -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  https://analytics.flowsery.com/api/v1/realtime

Returns { "data": [{ "visitors": 42 }] } — active visitors in the last 5 minutes.

For geographic data, use the map endpoint:

curl -s -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  https://analytics.flowsery.com/api/v1/realtime/map

5. Get breakdown reports

Each returns top items for a dimension with visitor/session counts. All accept date range, pagination, and filter params.

# Top pages
curl -s -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  "https://analytics.flowsery.com/api/v1/pages?startAt=2026-03-01&endAt=2026-03-31&limit=20"
Top referrers

curl -s -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  "https://analytics.flowsery.com/api/v1/referrers?startAt=2026-03-01&endAt=2026-03-31"
Countries

curl -s -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  "https://analytics.flowsery.com/api/v1/countries?startAt=2026-03-01&endAt=2026-03-31"
Devices (desktop/mobile/tablet)

curl -s -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  "https://analytics.flowsery.com/api/v1/devices?startAt=2026-03-01&endAt=2026-03-31"
Marketing channels

curl -s -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  "https://analytics.flowsery.com/api/v1/channels?startAt=2026-03-01&endAt=2026-03-31"

Available breakdown endpoints: pages, referrers, countries, regions, cities, devices, browsers, operating-systems, campaigns, hostnames, channels, goals.

For any dimension, use the generic breakdown:

curl -s -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  "https://analytics.flowsery.com/api/v1/breakdown?dimension=utm_source&startAt=2026-03-01&endAt=2026-03-31"

See references/breakdown-dimensions.md for all 24 dimensions.

6. Get a visitor profile

curl -s -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  https://analytics.flowsery.com/api/v1/visitors/VISITOR_ID_HERE

Returns comprehensive visitor data:

  • identity: country, region, city, browser, OS, device type, viewport
  • source: original traffic source with favicon URL
  • activity: visit count, page views, first/last visit, visited pages, completed goals
  • revenue: total revenue, customer flag, time to first conversion (seconds)
  • profile: identified user data (userId, name, email) or null for anonymous visitors
  • activityTimeline: merged chronological list of all pageviews, goals, and payments

    • The visitor ID comes from the _fs_vid browser cookie set by the Flowsery tracking script.

    7. Track a custom goal

    curl -X POST https://analytics.flowsery.com/api/v1/goals \
  -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "visitorUid": "VISITOR_UID_FROM_COOKIE",
    "name": "newsletter_signup",
    "metadata": { "plan": "pro", "source": "pricing_page" }
  }'

  • name (required): lowercase letters, numbers, underscores, hyphens; max 64 chars
  • visitorUid (recommended): from the _fs_vid browser cookie
  • metadata (optional): up to 10 key-value pairs (keys: lowercase, max 64 chars; values: max 255 chars)

    • The visitor must have at least one recorded pageview before a goal can be created.

    8. Record a payment

    > If you use Stripe, LemonSqueezy, or Polar, payments are tracked automatically when connected. Use this endpoint only for other providers.

    curl -X POST https://analytics.flowsery.com/api/v1/payments \
  -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 29.99,
    "currency": "USD",
    "transactionId": "payment_456",
    "visitorUid": "VISITOR_UID_FROM_COOKIE",
    "email": "customer@example.com"
  }'

    Required: amount, currency, transactionId. Optional: visitorUid, sessionUid, email, name, customerId, isRenewal (boolean), isRefund (boolean).

    9. Delete goal events

    curl -X DELETE "https://analytics.flowsery.com/api/v1/goals?name=signup&startAt=2026-01-01T00:00:00Z&endAt=2026-01-31T23:59:59Z" \
  -H "Authorization: Bearer $FLOWSERY_API_KEY"

    At least one filter required: visitorId, name, startAt, endAt.

    WARNING: Without a date range, matching records are deleted across the entire history.

    10. Delete payment records

    curl -X DELETE "https://analytics.flowsery.com/api/v1/payments?transactionId=payment_456" \
  -H "Authorization: Bearer $FLOWSERY_API_KEY"

    At least one filter required: transactionId, visitorId, startAt, endAt.

    WARNING: Without a date range, matching records are deleted across the entire history.

    Query Parameters

    Date range & pagination (all GET endpoints)

    | Param | Type | Description | | ---------- | ------- | -------------------------------------------------------------------- | | startAt | string | ISO 8601 start date (e.g. 2026-01-01) | | endAt | string | ISO 8601 end date (e.g. 2026-01-31) | | timezone | string | IANA timezone (e.g. America/New_York). Falls back to site default. | | limit | integer | Max results, 1-1000 (default: 100) | | offset | integer | Pagination offset (default: 0) |

    Filters (all GET endpoints)

    All filters use the filter_ prefix.

    | Filter | Description | | --------------------- | ---------------------------------------------- | | filter_country | Country name or code | | filter_region | Region or state | | filter_city | City name | | filter_device | Device type: desktop, mobile, tablet | | filter_browser | Browser: Chrome, Safari, Firefox, Edge | | filter_os | OS: Mac OS, Windows, iOS, Android | | filter_referrer | Referrer domain | | filter_ref | ref URL parameter value | | filter_source | source URL parameter value | | filter_via | via URL parameter value | | filter_utm_source | UTM source | | filter_utm_medium | UTM medium | | filter_utm_campaign | UTM campaign | | filter_utm_term | UTM term | | filter_utm_content | UTM content | | filter_page | Page path | | filter_hostname | Hostname/domain | | filter_entry_page | Landing page | | filter_channel | Marketing channel | | filter_goal | Goal name |

    Combine multiple filters to drill down:

    curl -s -H "Authorization: Bearer $FLOWSERY_API_KEY" \
  "https://analytics.flowsery.com/api/v1/pages?filter_country=United%20States&filter_device=mobile&startAt=2026-03-01&endAt=2026-03-31"

    Response Format

    Success (200 OK):

    {
  "status": "success",
  "data": { ... }
}

    Error:

    {
  "status": "error",
  "error": { "code": 401, "message": "A descriptive error message" }
}

    Error codes: 400 (invalid input), 401 (bad API key), 404 (not found), 500 (server error).

    Marketing Channels

    Flowsery auto-classifies traffic into GA4-aligned channels:

    | Channel | How it's classified | | -------------- | ------------------------------------------------------------------- | | Organic Search | Google, Bing, DuckDuckGo, etc. | | Paid Search | utm_medium: cpc, ppc, paid_search | | Organic Social | Facebook, Twitter, LinkedIn, Reddit, etc. | | Paid Social | utm_medium: paid_social, social_cpc | | Email | utm_medium: email, newsletter; or source: mailchimp, sendgrid, etc. | | Display | utm_medium: display, banner, cpm | | Referral | Other websites | | Direct | No referrer | | Affiliate | utm_medium: affiliate, partner | | Video | utm_medium: video, paid_video | | SMS | utm_medium: sms | | Audio | utm_medium: audio, podcast |

    Tips for the Agent

    Read-only by default

    Most commands are safe GET queries. The only write operations are:

  • POST /goals — track a goal event
  • POST /payments — record a payment
  • DELETE /goals — delete goal events (irreversible)
  • DELETE /payments — delete payment records (irreversible)

    • Always confirm with the user before running DELETE operations.

    Date handling

  • When the user says "this month", "last week", "yesterday" — calculate the actual ISO dates
  • Default to the last 30 days when no date range is specified
  • Always use UTC or the site's timezone (from the metadata endpoint)

    • Revenue data is sensitive

    When displaying payment or revenue data, ask the user about the appropriate level of detail before dumping raw numbers.

    Polling

    Do not poll the realtime endpoint more than once per 5 seconds.

    Common agent tasks

    | User says | What to do | | ---------------------------------- | ------------------------------------------------------------------------------------------- | | "How's my traffic?" | Call overview with last 30 days | | "What are my top pages?" | Call pages with date range | | "Where is my traffic coming from?" | Call referrers or channels | | "How many visitors right now?" | Call realtime | | "Show me traffic trends" | Call timeseries with interval=day | | "Who is this visitor?" | Call visitors/{id} | | "Track a signup" | Call POST /goals with name and visitor UID | | "How's my revenue?" | Call overview with fields=revenue,conversion_rate or timeseries with fields=revenue | | "Break down traffic by country" | Call countries | | "Show me mobile vs desktop" | Call devices | | "What campaigns are working?" | Call campaigns or breakdown?dimension=utm_source |

    ⚙️ Configuration

    1. Sign up at https://flowsery.com/signup 2. Add your website and install the tracking snippet 3. Go to Site Settings → API tab → generate an API key 4. Set the environment variable: 

       export FLOWSERY_API_KEY="flow_sk_live_your-token-here"

    Base URL: https://analytics.flowsery.com/api/v1 Auth header: Authorization: Bearer $FLOWSERY_API_KEY

    All API keys use the flow_ prefix (e.g. flow_sk_live_abc123). Treat them like passwords — never expose in client-side code.