Atlas Operations Analytics
Connection
Every Atlas task provides a base URL and an authorization header. Always start by
confirming connectivity and reading the live schema:
Available endpoints:
GET /api/schema -- table and column listings
GET /api/data-dictionary -- human-readable field descriptions
POST /api/sql -- read-only analytical SQL queries
POST /api/sql/transaction -- controlled data corrections (single-row updates)
GET /api/correction-audit -- audit records for past corrections
Use scripts/query_atlas.py for all HTTP calls. It accepts
the base URL, auth token, SQL string, and endpoint name (default sql).
Workflow
All analytical tasks follow a four-step pattern:
Step 1: Schema Discovery
Call GET /api/schema and GET /api/data-dictionary before writing any query.
These return plain JSON listing every table, column, and a human-readable
description of what each field means. Read both entirely -- assumptions about
column semantics without the dictionary are the leading source of wrong answers.
Identify which tables hold the core entities (orders, shipments, scans, tasks,
cases, refunds, accounts, warehouses, campaigns, fx rates) and their join keys.
Step 2: Understand the Business Request
The business request JSON (always named in the prompt) contains the complete
domain logic. Extract these critical sections before writing SQL:
- scope / cohort -- which rows qualify (time window, account tier, warehouse,
campaign, region, segment). Boundary rules:
inclusive means >= start and
<= end; treat timestamps as exact UTC.
- business definitions -- what "complete", "on time", "severe exception",
"backlog", "breach", or "leakage candidate" mean in SQL terms.
- metric formulas -- how rates, ratios, and aggregates are computed.
Rates always use the eligible population as denominator; incomplete items
remain in the denominator unless the definition explicitly excludes them.
- rounding rules -- typically "round only final reported rates to N decimal
places."
- classification rules -- tiered status logic (HEALTHY/WATCH/CRITICAL,
STABLE/PRESSURED/AT_RISK, CONTROLLED/ELEVATED/SEVERE, LOW/MODERATE/HIGH).
Apply rules in order; the first matching rule wins. A final "otherwise" or
"all other outcomes" rule catches everything else.
- output ordering -- how arrays must be sorted (ascending, descending,
multi-key tie-breaks).
See references/business_patterns.md for
common SQL translations of recurring business definitions.
Step 3: SQL Analysis
Write queries that match the cohort and compute the required metrics. Key
disciplines:
- Build the cohort first as a CTE or sub-select to keep later queries aligned.
- Compute intermediate states (per-order, per-shipment, per-case) before
aggregating.
- For time arithmetic: subtract timestamps and convert to hours or minutes. Do
not use string manipulation.
- For currency conversions: join
fx_rates on the service date and currency,
multiply the local amount by usd_per_unit.
- For medians: when the result count is even, average the two central values.
- Where exact lists are required (e.g. severe exception IDs, delayed task IDs),
include the
ORDER BY clause specified in the request.
Submit read-only queries to POST /api/sql. The endpoint accepts a JSON body
with a sql key.
Step 4: Compute and Format Answer
Do not write the final JSON from SQL alone. Pull raw results into the
execution context and perform final computations:
- Apply rounding only at the final step and only where specified.
- Apply classification rules using the computed rates.
- Sort arrays exactly as specified (multi-key with explicit direction per key).
- Check every field name, type, and constraint against the answer template.
- The output must be valid JSON with no extra keys, no commentary, and no
deviation from the template schema.
Transaction Workflow (Correction Tasks)
When the task includes a correction (always signaled by POST /api/sql/transaction
and an approved_correction section in the request payload):
- Query the raw data to find the contradictory row. Use the import batch,
warehouse, and cutoff from the request to narrow the search.
- Resolve the contradiction by comparing carrier raw status against the
canonical status. The correction is always to update the canonical field
to match the raw/true value.
- Submit the transaction via
POST /api/sql/transaction. The body is JSON
with sql (an UPDATE on a single row), audit_id, correction_key,
reason_code, actor, corrected_at, and the field/value details.
- Verify: run a post-change query on the corrected row to confirm the value.
- Query
GET /api/correction-audit to confirm exactly one audit row was
created.
- Report
APPLIED only when exactly one business row and one audit row
committed and the post-change query confirms the correction. Otherwise
report NOT_APPLIED.
Resources
- references/api_endpoints.md -- full endpoint
reference with request/response formats.
- references/business_patterns.md -- common
SQL patterns for translating business definitions into queries.
- scripts/query_atlas.py -- reusable Python script for
all Atlas HTTP API calls.
1---2name: atlas-ops-analytics-43description: "Atlas Commerce Operations analytics platform access for business scorecards, operational reconciliations, quality reviews, productivity reports, and support health reviews. Use when working with the Atlas Commerce Operations API to query business records through schema discovery and SQL analysis, compute operational metrics from business request definitions, apply business classification rules to produce structured answer templates, or execute controlled data corrections with audit records. Trigger when a task references an Atlas Commerce Operations workplace, the /api/schema or /api/sql endpoint, answer_template.json, a cutoff-based operational scorecard, or payloads containing business definitions and classification rules."4license: MIT5compatibility: designed for deepagents-code6metadata:7 source: https://skillmd.com/skills/prism-shadow/atlas-ops-analytics-48---910# Atlas Operations Analytics1112## Connection1314Every Atlas task provides a base URL and an authorization header. Always start by15confirming connectivity and reading the live schema:16171819Available endpoints:20- `GET /api/schema` -- table and column listings21- `GET /api/data-dictionary` -- human-readable field descriptions22- `POST /api/sql` -- read-only analytical SQL queries23- `POST /api/sql/transaction` -- controlled data corrections (single-row updates)24- `GET /api/correction-audit` -- audit records for past corrections2526Use [scripts/query_atlas.py](scripts/query_atlas.py) for all HTTP calls. It accepts27the base URL, auth token, SQL string, and endpoint name (default `sql`).2829## Workflow3031All analytical tasks follow a four-step pattern:3233### Step 1: Schema Discovery3435Call `GET /api/schema` and `GET /api/data-dictionary` before writing any query.36These return plain JSON listing every table, column, and a human-readable37description of what each field means. Read both entirely -- assumptions about38column semantics without the dictionary are the leading source of wrong answers.3940Identify which tables hold the core entities (orders, shipments, scans, tasks,41cases, refunds, accounts, warehouses, campaigns, fx rates) and their join keys.4243### Step 2: Understand the Business Request4445The business request JSON (always named in the prompt) contains the complete46domain logic. Extract these critical sections before writing SQL:4748- **scope / cohort** -- which rows qualify (time window, account tier, warehouse,49 campaign, region, segment). Boundary rules: `inclusive` means `>=` start and50 `<=` end; treat timestamps as exact UTC.51- **business definitions** -- what "complete", "on time", "severe exception",52 "backlog", "breach", or "leakage candidate" mean in SQL terms.53- **metric formulas** -- how rates, ratios, and aggregates are computed.54 Rates always use the eligible population as denominator; incomplete items55 remain in the denominator unless the definition explicitly excludes them.56- **rounding rules** -- typically "round only final reported rates to N decimal57 places."58- **classification rules** -- tiered status logic (HEALTHY/WATCH/CRITICAL,59 STABLE/PRESSURED/AT_RISK, CONTROLLED/ELEVATED/SEVERE, LOW/MODERATE/HIGH).60 Apply rules in order; the first matching rule wins. A final "otherwise" or61 "all other outcomes" rule catches everything else.62- **output ordering** -- how arrays must be sorted (ascending, descending,63 multi-key tie-breaks).6465See [references/business_patterns.md](references/business_patterns.md) for66common SQL translations of recurring business definitions.6768### Step 3: SQL Analysis6970Write queries that match the cohort and compute the required metrics. Key71disciplines:7273- Build the cohort first as a CTE or sub-select to keep later queries aligned.74- Compute intermediate states (per-order, per-shipment, per-case) before75 aggregating.76- For time arithmetic: subtract timestamps and convert to hours or minutes. Do77 not use string manipulation.78- For currency conversions: join `fx_rates` on the service date and currency,79 multiply the local amount by `usd_per_unit`.80- For medians: when the result count is even, average the two central values.81- Where exact lists are required (e.g. severe exception IDs, delayed task IDs),82 include the `ORDER BY` clause specified in the request.8384Submit read-only queries to `POST /api/sql`. The endpoint accepts a JSON body85with a `sql` key.8687### Step 4: Compute and Format Answer8889Do not write the final JSON from SQL alone. Pull raw results into the90execution context and perform final computations:9192- Apply rounding only at the final step and only where specified.93- Apply classification rules using the computed rates.94- Sort arrays exactly as specified (multi-key with explicit direction per key).95- Check every field name, type, and constraint against the answer template.96- The output must be valid JSON with no extra keys, no commentary, and no97 deviation from the template schema.9899## Transaction Workflow (Correction Tasks)100101When the task includes a correction (always signaled by `POST /api/sql/transaction`102and an `approved_correction` section in the request payload):1031041. Query the raw data to find the contradictory row. Use the import batch,105 warehouse, and cutoff from the request to narrow the search.1062. Resolve the contradiction by comparing carrier raw status against the107 canonical status. The correction is always to update the canonical field108 to match the raw/true value.1093. Submit the transaction via `POST /api/sql/transaction`. The body is JSON110 with `sql` (an UPDATE on a single row), `audit_id`, `correction_key`,111 `reason_code`, `actor`, `corrected_at`, and the field/value details.1124. Verify: run a post-change query on the corrected row to confirm the value.1135. Query `GET /api/correction-audit` to confirm exactly one audit row was114 created.1156. Report `APPLIED` only when exactly one business row and one audit row116 committed and the post-change query confirms the correction. Otherwise117 report `NOT_APPLIED`.118119## Resources120121- [references/api_endpoints.md](references/api_endpoints.md) -- full endpoint122 reference with request/response formats.123- [references/business_patterns.md](references/business_patterns.md) -- common124 SQL patterns for translating business definitions into queries.125- [scripts/query_atlas.py](scripts/query_atlas.py) -- reusable Python script for126 all Atlas HTTP API calls.