@lionhummer/constellation 0.9.2 → 0.9.4

package/README.md

@@ -341,6 +341,8 @@ tools: {
 },
 ```
 
+Work you do before the first model step, such as loading context and building the prompt, can travel with the request that starts the run: pass `telemetry: { spans, logs }` to `requests.submit`. Those spans belong to the request rather than a step: they sit at the top of the timeline at their own timestamps, before the first step (set `stepId` or `parentSpanId` to nest them elsewhere).
+
 The SDK records `client.processing` and one span per tool automatically. A response carries at most 512 spans, 128 logs and 1 MiB of telemetry; the SDK trims larger batches and records what it omitted. Do not put secrets or personal data in span names, attributes or log messages.
 
 ## Opening lines
@@ -361,6 +363,45 @@ if (opener) void client.openers.sentence(opener.id).then((sentence) => {
 
 Start the real request without waiting for the opener. `parseOpenerSentence(text)` applies the same checks to text you already have.
 
+## Telemetry queries
+
+Ask aggregate questions without SQL. Fields, filters and metrics are typed per dataset.
+
+```ts
+// How many fireworks-direct attempts failed yesterday, and why?
+const failures = await client.telemetry.query({
+  dataset: "attempts",
+  from: "2026-10-15T00:00:00Z", to: "2026-10-16T00:00:00Z",
+  where: { offeringId: { startsWith: "fireworks-direct:" }, status: "failed" },
+  groupBy: ["errorCode", "httpStatus"],
+  metrics: ["count", "uniq:requestId"],
+})
+
+// How often did a provider say "Response too long", per day?
+const mentions = await client.telemetry.query({
+  dataset: "attempts",
+  from: "2026-10-01T00:00:00Z", to: "2026-10-16T00:00:00Z",
+  where: { errorMessage: { contains: "Response too long" } },
+  groupBy: ["day"],
+})
+```
+
+Usage and costs come from the permanent billing record (`usage`, one row per settled request, or `usageAttempts`, one row per provider attempt for provider/model splits). Any range works:
+
+```ts
+// Customer charges, supplier cost and margin per workspace and provider last month, without QA
+const byProvider = await client.telemetry.query({
+  dataset: "usageAttempts",
+  from: "2026-09-01T00:00:00Z", to: "2026-10-01T00:00:00Z",
+  where: { workspaceId: { notIn: ["qa"] } },
+  groupBy: ["workspaceId", "providerId"],
+  metrics: ["uniq:requestId", "sum:customerCost", "sum:supplierCost", "sum:margin"],
+  limit: 10000,
+})
+```
+
+A scoped key only ever sees its workspace and user. Logs and usage need an unscoped key. Telemetry ranges are at most 92 days and results at most 1,000 rows; usage allows any range and 10,000 rows. Group by `minute`, `hour`, `day`, `week` or `month` for time series.
+
 ## Limits and timeouts
 
 | Setting | Default | Notes |
@@ -394,6 +435,7 @@ A failed provider call falls back to the next provider only before any output ha
 | `requests.getTimeline(id)`, `requests.getTimings(id)` | Trace and timing breakdown. |
 | `requests.getHttpExchange(id, attemptId)`, `requests.getHttpBody(...)` | The provider HTTP call captured for one attempt. |
 | `webhooks.verify(request, token)` | Authenticate and parse an incoming webhook. |
+| `telemetry.query(query)` | Count, group and aggregate attempts, requests, logs or permanent usage, e.g. failed attempts per offering and error code, or cost per workspace and provider. Needs telemetry permission; the key's scope always applies. |
 | `telemetry.*` | Read-only reporting. Returns metadata only unless you pass `include: "content"`. Needs telemetry permission. |
 | `management.registry.*` | Edit the model registry. Needs management permission. |
 | `discover()` | The OpenAPI document for exactly what this key may call. |

package/dist/index.js

@@ -764,6 +764,10 @@ class Constellation extends RequestClient {
         get: (id, query = {}, signal) => this.#call(`/v1/telemetry/notifications/${encodeURIComponent(id)}${queryString2(query)}`, "GET", undefined, signal),
         listEvents: (query = {}, signal) => this.#call(`/v1/telemetry/notifications/events${queryString2(query)}`, "GET", undefined, signal)
       },
+      query: (query, signal) => {
+        const iso = (value) => value instanceof Date ? value.toISOString() : value;
+        return this.#call("/v1/telemetry/query", "POST", { ...query, from: iso(query.from), to: iso(query.to) }, signal);
+      },
       logs: {
         searchSystem: (query = {}, signal) => this.#call(`/v1/telemetry/logs/system${queryString2(query)}`, "GET", undefined, signal),
         searchRequests: (query = {}, signal) => this.#call(`/v1/telemetry/logs/requests${queryString2(query)}`, "GET", undefined, signal),

package/dist/types/sdk/src/index.d.ts

@@ -28,6 +28,63 @@ export type TelemetryPage<T> = Page<T> & {
 export type TelemetryQuery = {
     include?: "content";
 };
+/** Fields of each aggregate dataset, as POST /v1/telemetry/query accepts them. */
+export type AttemptField = "workspaceId" | "userId" | "externalId" | "requestId" | "providerId" | "offeringId" | "model" | "requestedModel" | "status" | "fallback" | "dispatched" | "errorCode" | "faultClass" | "httpStatus" | "errorMessage";
+export type AttemptNumber = "ttftMs" | "latencyMs" | "outputTokens" | "supplierCost" | "customerCost" | "httpStatus";
+export type RequestField = "workspaceId" | "userId" | "externalId" | "requestId" | "requestedModel" | "status";
+export type RequestNumber = "durationMs" | "supplierCost" | "customerCost";
+export type LogField = "level" | "name" | "status" | "requestId" | "message";
+/** Permanent billing record per settled request (unscoped telemetry keys only). */
+export type UsageField = "workspaceId" | "userId" | "externalId" | "requestId" | "requestedModel" | "planId" | "status";
+type UsageTotals = "supplierCost" | "customerCost" | "margin" | "inputTokens" | "cacheReadTokens" | "cacheWriteTokens" | "cacheWriteOneHourTokens" | "outputTokens" | "reasoningTokens";
+export type UsageNumber = UsageTotals | "durationMs";
+/** Permanent billing record per provider attempt; `status` is the attempt's, `requestStatus` the request's. */
+export type UsageAttemptField = Exclude<UsageField, "status"> | "requestStatus" | "providerId" | "model" | "providerModel" | "status";
+export type UsageAttemptNumber = UsageTotals;
+export type AggregateTimeGroup = "minute" | "hour" | "day" | "week" | "month";
+export type AggregateScalar = string | number | boolean;
+/** A value, any of several values, or operators combined with AND. `contains` is case-insensitive. */
+export type AggregateFilter = AggregateScalar | AggregateScalar[] | {
+    eq?: AggregateScalar;
+    in?: AggregateScalar[];
+    not?: AggregateScalar;
+    notIn?: AggregateScalar[];
+    contains?: string;
+    startsWith?: string;
+    gte?: number;
+    gt?: number;
+    lte?: number;
+    lt?: number;
+    /** true: the field has a value; false: it is empty. */
+    exists?: boolean;
+};
+export type AggregateMetric<N extends string, F extends string> = "count" | `uniq:${F}` | `${"sum" | "avg" | "min" | "max" | "p50" | "p90" | "p95" | "p99"}:${N}`;
+type AggregateShape<D extends string, F extends string, N extends string> = {
+    dataset: D;
+    /** Inclusive start and exclusive end; at most 92 days apart (usage datasets: any range). */
+    from: string | Date;
+    to: string | Date;
+    where?: Partial<Record<F | N, AggregateFilter>>;
+    /** At most four. Numeric fields other than httpStatus are aggregated, not grouped. */
+    groupBy?: (F | AggregateTimeGroup)[];
+    /** One to eight; default ["count"]. */
+    metrics?: AggregateMetric<N, F>[];
+    orderBy?: {
+        by: string;
+        descending?: boolean;
+    };
+    /** Default 100, at most 1,000 rows (usage datasets: 10,000). */
+    limit?: number;
+};
+/** A structured aggregate over telemetry facts or permanent usage. The key's workspace/user scope always applies; logs and usage need an unscoped key. */
+export type AggregateQuery = AggregateShape<"attempts", AttemptField, AttemptNumber> | AggregateShape<"requests", RequestField, RequestNumber> | AggregateShape<"logs", LogField, never> | AggregateShape<"usage", UsageField, UsageNumber> | AggregateShape<"usageAttempts", UsageAttemptField, UsageAttemptNumber>;
+export type AggregateResult = {
+    /** Groupings first, then metrics, in request order. */
+    columns: string[];
+    rows: Record<string, Json>[];
+    /** More groups matched than `limit`. */
+    truncated: boolean;
+};
 export type TelemetryReadOptions = TelemetryQuery & {
     signal?: AbortSignal;
 };
@@ -191,6 +248,8 @@ export declare class Constellation extends RequestClient {
                 after?: number;
             }, signal?: AbortSignal) => Promise<Json>;
         };
+        /** Count, group and aggregate attempts, requests or logs, e.g. failed attempts per offering and error code. */
+        query: (query: AggregateQuery, signal?: AbortSignal) => Promise<AggregateResult>;
         logs: {
             searchSystem: (query?: LogSearchQuery & TelemetryQuery, signal?: AbortSignal) => Promise<Page<Json>>;
             searchRequests: (query?: Omit<LogSearchQuery, "level" | "levelNot" | "target" | "targetNot"> & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lionhummer/constellation",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "TypeScript client for durable model requests and model events",
   "type": "module",
   "license": "UNLICENSED",