Metriqal Documentation

Overview

Metriqal runs on your competitor Steam App IDs alone. Optionally, it ingests internal signal streams from your studio — developer velocity (Jira/GitHub), player sentiment (Discord), and player telemetry — to enrich the correlation against live competitor market signals, then emits a single executable recommendation with measured impact (incremental lift measured via holdout / geo-split where available).

This guide walks from zero to your first recommendation. You'll need your studio's credentials (delivered by email at signup). The internal streams below are optional enrichment — connect Jira/GitHub, Discord, or your telemetry only if you want those signals layered in; none are required to start.

Step 1 — Connect Webhooks

Each credential email includes three webhook endpoints. Configure whichever signals you want to use:

Jira

In Jira: Project Settings → Webhooks → Create Webhook. Set the URL to your jira_endpoint and enable events: Sprint started, Sprint closed, Issue resolved. Set the secret header X-Jira-Signature to your jira_webhook_secret.

GitHub

In your repo: Settings → Webhooks → Add Webhook. Set the Payload URL to your github_endpoint. Content type: application/json. Secret: your github_webhook_secret. Events: Pull requests, Issues.

Discord

In your server: any bot or webhook integration that can POST messages to your discord_endpoint with the header Authorization: Bearer <discord_webhook_secret>. Each message is run through sentiment analysis automatically.

Step 2 — Ingest Telemetry

POST player events to your ingest endpoint. Your studio_portal_key (spk_...) is the auth token. Include your game's game_id (from the studio portal) and the current build_tag:

POST /api/ingest
Authorization: Bearer spk_...
Content-Type: application/json

{
  "game_id":    "550e8400-e29b-41d4-a716-446655440000",
  "build_tag":  "v2.4.1",
  "player_id":  "player_abc123",
  "event_type": "session_start",
  "event_ts":   "2026-05-29T09:00:00Z"
}

Step 3 — Read Your First Recommendation

Once enough telemetry has accumulated (24–48 hours), call the recommendations endpoint:

GET /api/games/{game_id}/recommendations/latest?build_tag=v2.4.1
X-Metriqal-Portal-Key: spk_...

The legacy confidence_score field is uncalibrated heuristic priority (0 to 1), not an outcome probability.

{
  "recommendation_type": "aggressive_uacq",
  "confidence_score": 0.87,
  "data_tier": "tier_2_telemetry",
  "is_algorithmic_fallback": false,
  "upgrade_prompt": null,
  "confidence_degradation_reason": null,
  "generated_at": "2026-06-06T09:00:00.000Z",
  "rationale": "Rival Arena: Champions CCU down 38% in 48h. Your retention holding at 0.94. Acquisition window open.",
  "execution_payload": {
    "action_type":    "increase_ad_spend",
    "target_metric":  "marketing_budget",
    "suggested_value": 1.5,
    "priority":       "high"
  },
  "log_id": "a1b2c3d4-..."
}

Save the log_id. You'll use it to submit your outcome 7 days later so the engine can compute the measured impact (an internal before/after effect-size estimate; directional unless you ran a holdout).

Authentication

All studio-facing API endpoints require your studio portal key (spk_... prefix). Pass it in the X-Metriqal-Portal-Key header.

X-Metriqal-Portal-Key: spk_abc123...

Keys are tenant-scoped. Requests using a valid key for a different tenant return 403 Forbidden. Missing or invalid keys return 401 Unauthorized.

Studio Portal API

{ "title": "My Game", "genre": "Action", "platforms": ["Steam"] }

{ "steam_app_id": "730", "platform": "steam" }

Telemetry Ingestion

Recommendations

Query parameters

Recommendation types

Response headers

Market Context

{
  "own_game": {
    "game_id":        "550e8400-...",
    "title":          "My Game",
    "units":          84200,
    "ccu_peak":       3100,
    "is_estimate":    false,
    "data_source":    "first_party_telemetry",
    "confidence":     "measured"
  },
  "competitor_estimates": [
    {
      "steam_app_id":           "730",
      "competitor_name":        "Rival Arena: Champions",
      "total_estimated_units":  420000,
      "is_estimate":           true,
      "confidence":            "medium",
      "coverage_score":        0.74
    }
  ]
}

Outcomes

Submit metric deltas 7 days after executing a recommendation. Metriqal runs a before/after significance test automatically and returns a measured-impact estimate (lift evidence — directional unless you ran a holdout / geo-split).

{
  "measured_retention_delta": 4.2,   // percentage points
  "measured_velocity_delta":  null,   // null if not measurable
  "pre_retention":            0.88,
  "cohort_size":              1200
}

The response includes p_value, confidence_level, and observed_effect ("lift" | "regress" | "neutral" | "insufficient_signal"). Legacy aggregate inputs do not support inference: p-value and confidence level are null; effects remain descriptive.

Webhooks

All webhook endpoints are provisioned at signup. Secrets are per-tenant and rotatable from the studio portal.

Data Export

Responses carry the header X-GS-CompInt-Version: GS-CompInt-2026. The export is yours to keep — no Metriqal dependency required to read or validate it.

The Open Competitive Intelligence Standard

GS-CompInt-2026 is an open data standard for game studio competitive intelligence. It specifies a portable, vendor-neutral format for competitor incidents, studio outcomes, correlation signals, and playbook definitions.

Any tool that can read JSON can read a GS-CompInt-2026 export. You're not locked in to Metriqal's platform to use your own data.

Schema

A GS-CompInt-2026 document is a JSON object with four top-level fields:

{
  "version": "GS-CompInt-2026",
  "incidents": [ /* MarketIncident[] */ ],
  "outcomes": [ /* RecommendationOutcome[] */ ],
  "correlation": [ /* CorrelationSnapshot[] */ ],
  "playbooks": [ /* PlaybookDefinition[] */ ]
}

MarketIncident

{
  "competitor_game_id": "string (UUID)",
  "competitor_build_tag": "string (semver)",
  "incident_type": "patch_day | server_outage | content_drop | live_event | emergency_fix | api_breaking",
  "source_ts": "ISO 8601"
}

RecommendationOutcome

{
  "log_id": "string (UUID)",
  "recommendation_type": "string",
  "measured_retention_delta": "number | null",
  "p_value": "number | null",
  "confidence_level": "number | null",
  "observed_effect": "lift | regress | neutral | insufficient_signal | null"
}

CorrelationSnapshot

{
  "game_id": "string (UUID)",
  "build_tag": "string (semver)",
  "velocity_dau_pct": "number",
  "retention_inverse": "number",
  "sentiment_score": "number",
  "queried_at": "ISO 8601"
}

Discovery Endpoint

Third-party tools can discover the current schema version without cloning this repo:

GET https://metriqal.se/.well-known/gs-compint-2026.json

// Response header:
X-GS-CompInt-Version: GS-CompInt-2026

Validator CLI

Validate any GS-CompInt-2026 document without a Metriqal account:

# Via npm
npx gs-compint-validate path/to/export.json

# Via Metriqal's built-in script
npm run validate-outcome -- path/to/export.json

Exit codes

Open-Source Outcome Validator

The outcome validator runs a two-proportion z-test on pre/post recommendation retention deltas to estimate whether an observed change is a measurable effect — or could plausibly be explained by random variance. This is an internal effect-size indicator, not proof of causation; a single-cohort before/after test is directional unless you ran a holdout / geo-split control.

The math is open. You can audit it, run it locally, or integrate it into your own data warehouse. No Metriqal account required.

Usage

npm run validate-outcome -- export.json

# Or pipe a JSON document directly:
cat export.json | npx gs-compint-validate

The validator reads outcomes[] from a GS-CompInt-2026 export and prints a verdict per outcome:

✓ log_id: a1b2c3... LIFT                p=0.031  retention_delta=+4.2pts
~ log_id: d4e5f6... INSUFFICIENT_SIGNAL  p=0.112  cohort below minimum
✗ log_id: g7h8i9... REGRESS              p=0.008  delta in wrong direction

Statistical Model

Retention is a proportion (players retained ÷ cohort size), so its variance is structurally p(1-p)/n - a two-proportion z-test uses this binomial variance directly. Welch's t-test would instead make the test statistic grow with the square root of cohort size regardless of effect size, manufacturing significance for trivial retention changes at large cohorts. Continuous metrics (revenue per player, playtime) are a different measurement type and do use Welch's t-test - see the GS-CompInt-2026 spec, section 5.1 for why the two are not interchangeable.

Inputs

• pre_retention — baseline retention rate before the recommendation was executed
• measured_retention_delta — observed change in retention after 7 days
• cohort_size — number of players in the measurement window

Thresholds

Limitations — When Not to Use This Test

• Legacy aggregate retention inputs cannot establish separate independent comparison arms. The current legacy API returns descriptive effects with p_value: null and confidence_level: null, regardless of a single cohort count.
• Measurement window < 7 days — behavioural changes take time to manifest in retention metrics. Submit outcomes after the full window.
• Multiple simultaneous changes — if you shipped a patch and ran a UA campaign simultaneously, you cannot attribute the delta to either independently.
• Velocity delta — DAU velocity is not computed by the retrospective validator because the pre-action baseline cannot be reliably reconstructed from retention-only data. This field is always stored as null.