# Episodes_SummarizeEpisodes

`GET /v1/accounts/{account}/datasets/{dataset}/episodes:summarize`

Counts, facets and metric distributions over the episodes a filter leaves:
what the filter chips, the status bar and the outlier cards read.

- Base URL: `https://junction-api.qualiastudios.dev`
- Authentication: an API key in the `X-API-Key` header

## Parameters

- `account` (path, string, required): The account id.
- `dataset` (path, string, required): The dataset id.
- `filter` (query, string): Same language as ListEpisodes.filter.
- `facets` (query, array of string): Facet fields to count, e.g. "state", "open_issue_codes", "note_codes", "task",
  "instruction", "tags",
  "operator", "method", "methods", "scene", "rig", "upload", "outcome",
  "linked_task",
  "metrics.quality_tier", "metrics.jerky", "viewed", "decision.actor.kind".
  Empty means state only.
- `metrics` (query, array of string): Metric fields to describe, e.g. "metrics.duration_seconds".
- `binCount` (query, integer (int32)): Histogram bins per metric; 0 means 30.

## Responses

- `200` OK: `application/json` `qualia.v1.SummarizeEpisodesResponse`
- `default` Default error response: `application/json` `google.rpc.Status`

## Schemas

```yaml
qualia.v1.SummarizeEpisodesResponse:
  type: object
  properties:
    episodeCount:
      type: string
      description: Episodes the filter leaves.
    durationSeconds:
      type: number
      description: Their recorded time, seconds.
      format: double
    frameCount:
      type: string
      description: Frames.
    facets:
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.SummarizeEpisodesResponse_Facet"
      description: One per requested facet.
    distributions:
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.SummarizeEpisodesResponse_Distribution"
      description: One per requested metric.
  description: Response for Episodes.SummarizeEpisodes.
qualia.v1.SummarizeEpisodesResponse_Facet:
  type: object
  properties:
    field:
      type: string
      description: The facet field.
    buckets:
      type: array
      items:
        $ref: "#/components/schemas/qualia.v1.Facet_Bucket"
      description: Buckets, largest first.
    otherCount:
      type: string
      description: Distinct values beyond the buckets returned.
  description: "One facet: counts per value."
qualia.v1.Facet_Bucket:
  type: object
  properties:
    value:
      type: string
      description: The value, as the filter spells it.
    count:
      type: string
      description: Episodes carrying it.
  description: One value and how many episodes carry it.
qualia.v1.SummarizeEpisodesResponse_Distribution:
  type: object
  properties:
    field:
      type: string
      description: The metric field.
    sampleCount:
      type: string
      description: Episodes with a value.
    quantiles:
      type: array
      items:
        type: number
        format: double
      description: p05, p10, p25, p50, p75, p90, p95.
    binEdges:
      type: array
      items:
        type: number
        format: double
      description: Bin edges, bin_count + 1 values.
    binCounts:
      type: array
      items:
        type: string
      description: Episodes per bin.
    fenceLow:
      type: number
      description: |-
        Lower and upper fences the checks use for this metric in this dataset
        (Q1 - 3 IQR, Q3 + 3 IQR over its robot's reference); NaN when unfenced.
      format: double
    fenceHigh:
      type: number
      description: Upper fence.
      format: double
  description: One metric's distribution over the filtered episodes.
google.rpc.Status:
  oneOf:
    - $ref: "#/components/schemas/ApiError"
    - $ref: "#/components/schemas/GatewayError"
  description: "The body of a failed call: one of the two shapes below."
ApiError:
  title: API error
  type: object
  required:
    - code
    - message
    - retryable
    - details
  properties:
    code:
      type: string
      description: The gRPC code name in upper case, e.g. `NOT_FOUND`.
    message:
      type: string
    retryable:
      type: boolean
      description: Whether the same call may succeed if retried.
    details:
      type: array
      items:
        type: object
      description: "Empty, except when a dataset copy or move is refused: then one `google.rpc.ErrorInfo` with the refusal's `reason` code, its `domain` and, in `metadata`, the datasets it names."
  description: A refusal from the API itself.
GatewayError:
  title: Gateway error
  type: object
  required:
    - detail
  properties:
    detail:
      type: string
      description: What went wrong.
  description: A refusal from the gateway before the call reaches the API, for example `401` bad or missing API key, `403` key lacks the scope or environment closed, `413` body too large.
```