> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.datalab.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Session Snapshot

> The whole session view-model in one poll: state (draft, pending, docs,
versions, jobs) + the events past the cursor.



## OpenAPI

````yaml https://www.datalab.to/openapi.json get /api/v1/agent-studio/sessions/{session_id}/snapshot
openapi: 3.1.0
info:
  title: Datalab API
  version: 0.0.1
servers:
  - url: https://www.datalab.to
    description: Datalab API
security: []
paths:
  /api/v1/agent-studio/sessions/{session_id}/snapshot:
    get:
      tags:
        - agent-studio
      summary: Get Session Snapshot
      description: |-
        The whole session view-model in one poll: state (draft, pending, docs,
        versions, jobs) + the events past the cursor.
      operationId: >-
        get_session_snapshot_api_v1_agent_studio_sessions__session_id__snapshot_get
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: integer
            title: Session Id
        - name: since_seq
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            description: Return events with seq > since_seq (poll cursor).
            default: 0
            title: Since Seq
          description: Return events with seq > since_seq (poll cursor).
        - name: wos-session
          in: cookie
          required: false
          schema:
            type: string
            title: Wos-Session
        - name: datalab_active_team
          in: cookie
          required: false
          schema:
            type: string
            title: Datalab Active Team
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSnapshotResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    SessionSnapshotResponse:
      properties:
        session:
          $ref: '#/components/schemas/SessionStateResponse'
        events:
          items:
            $ref: '#/components/schemas/SessionEventResponse'
          type: array
          title: Events
        cursor:
          type: integer
          title: Cursor
          description: Max event seq served; pass back as since_seq on the next poll.
      type: object
      required:
        - session
        - cursor
      title: SessionSnapshotResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SessionStateResponse:
      properties:
        id:
          type: integer
          title: Id
        title:
          type: string
          title: Title
        status:
          type: string
          enum:
            - active
            - committed
            - published
            - archived
          title: Status
        phase:
          type: string
          enum:
            - grounding
            - drafting
            - exercising
            - iterating
            - ready
            - frozen
          title: Phase
        template_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Template Id
        base_profile:
          anyOf:
            - type: string
            - type: 'null'
          title: Base Profile
        processor_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Processor Id
          description: Public processor slug once the first commit ran.
        draft_contract:
          $ref: '#/components/schemas/ContractModel'
        draft_checks:
          items:
            $ref: '#/components/schemas/CheckSpecModel'
          type: array
          title: Draft Checks
        pending:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Pending
          description: 'The single pending card: {kind: question|diff, payload, event_seq}.'
        docs:
          items:
            $ref: '#/components/schemas/ReferenceDocResponse'
          type: array
          title: Docs
        versions:
          items:
            $ref: '#/components/schemas/VersionResponse'
          type: array
          title: Versions
        jobs:
          items:
            $ref: '#/components/schemas/SessionJobResponse'
          type: array
          title: Jobs
        rescores:
          items:
            $ref: '#/components/schemas/SessionRescoreResponse'
          type: array
          title: Rescores
          description: >-
            Verify-only overlays, one per run with a live or done verify
            (verify-only-plan §7). Additive-optional: absent/empty for sessions
            that never re-checked.
        draft_checks_fingerprint:
          type: string
          title: Draft Checks Fingerprint
          description: >-
            The CURRENT draft's execution-relevant check fingerprint — rescores
            whose checks_fingerprint differs are STALE.
          default: ''
        token_usage:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Token Usage
        last_consumed_seq:
          type: integer
          title: Last Consumed Seq
          default: 0
        created:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created
        updated:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated
      type: object
      required:
        - id
        - title
        - status
        - phase
        - draft_contract
      title: SessionStateResponse
    SessionEventResponse:
      properties:
        id:
          type: integer
          title: Id
        seq:
          type: integer
          title: Seq
        ts:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Ts
        kind:
          type: string
          title: Kind
        actor:
          type: string
          enum:
            - user
            - agent
            - system
          title: Actor
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
          description: Convenience copy of payload.text when present.
        payload:
          additionalProperties: true
          type: object
          title: Payload
        refs:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Refs
      type: object
      required:
        - id
        - seq
        - kind
        - actor
      title: SessionEventResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ContractModel:
      properties:
        goal:
          type: string
          title: Goal
        output_shape:
          type: string
          enum:
            - parse
            - json
            - jats
            - wcag
            - segment
          title: Output Shape
        output_schema:
          anyOf:
            - type: string
            - type: 'null'
          title: Output Schema
        rules:
          items:
            $ref: '#/components/schemas/RuleFragmentModel'
          type: array
          title: Rules
        parse_params:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Parse Params
        knobs:
          anyOf:
            - $ref: '#/components/schemas/KnobsModel'
            - type: 'null'
      type: object
      required:
        - goal
        - output_shape
      title: ContractModel
      description: The freezable record a version snapshots (contract JSONB).
    CheckSpecModel:
      properties:
        id:
          type: string
          title: Id
        label:
          type: string
          title: Label
        description:
          type: string
          title: Description
          default: ''
        kind:
          type: string
          enum:
            - code
            - judge
          title: Kind
        blocking:
          type: boolean
          title: Blocking
          default: false
        source:
          type: string
          enum:
            - base
            - catalog
            - user
          title: Source
          default: base
        modified_from_base:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Modified From Base
      type: object
      required:
        - id
        - label
        - kind
      title: CheckSpecModel
      description: One verifier in the contract (frontend CheckSpec, snake_case).
    ReferenceDocResponse:
      properties:
        id:
          type: integer
          title: Id
        name:
          type: string
          title: Name
        page_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Page Count
          description: >-
            Surface count of `doc_kind` surfaces: pages for page docs, SHEETS
            for sheet docs (spreadsheets have no pages — sheet path, plan A7).
            Always None for text docs.
        doc_kind:
          anyOf:
            - type: string
              enum:
                - page
                - sheet
                - text
            - type: 'null'
          title: Doc Kind
          description: >-
            What page_count counts (the locator surface vocabulary); 'text' =
            context-only .md/.txt doc. None = legacy row, page semantics.
        role:
          type: string
          enum:
            - process
            - context
          title: Role
          description: >-
            What the doc is FOR (D1): 'process' docs are exercised by
            commits/launches; 'context' docs feed the agent's context and never
            launch runs.
          default: process
        role_locked:
          type: boolean
          title: Role Locked
          description: >-
            True for text docs — they can only be context (no converter on the
            agent path covers text).
          default: false
        created:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created
      type: object
      required:
        - id
        - name
      title: ReferenceDocResponse
    VersionResponse:
      properties:
        label:
          type: string
          title: Label
        state:
          type: string
          enum:
            - draft
            - committed
            - published
          title: State
        contract:
          $ref: '#/components/schemas/ContractModel'
        checks:
          items:
            $ref: '#/components/schemas/CheckSpecModel'
          type: array
          title: Checks
        caused_by:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Caused By
        created:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created
      type: object
      required:
        - label
        - state
        - contract
        - checks
      title: VersionResponse
    SessionJobResponse:
      properties:
        id:
          type: integer
          title: Id
          description: >-
            KIND-SCOPED row id: the agentrun id for kind=doc_run, the
            agentverify id for kind=verify_only — the two id spaces overlap, so
            consumers must key on (kind, id), never id alone. run_id always
            names the agentrun (the TARGET run for verify jobs); run refreshers
            must guard on kind === 'doc_run'.
        kind:
          type: string
          enum:
            - parse
            - doc_run
            - verify_only
            - optimize
          title: Kind
          default: doc_run
        label:
          type: string
          title: Label
        pinned_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Pinned Version
        status:
          type: string
          enum:
            - running
            - done
            - failed
          title: Status
        run_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Run Id
        doc_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Doc Name
          description: >-
            Input document name — served directly so mid-poll job rows never
            need a per-run hydration.
        started:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started
        finished:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Finished
      type: object
      required:
        - id
        - label
        - status
      title: SessionJobResponse
      description: |-
        One design-plane job line (types.ts Job). ``status`` collapses the
        row vocabulary: queued|running -> running, done -> done, error ->
        failed.
    SessionRescoreResponse:
      properties:
        run_id:
          type: integer
          title: Run Id
          description: The TARGET agentrun id.
        verify_id:
          type: integer
          title: Verify Id
          description: The agentverify row id.
        status:
          type: string
          enum:
            - queued
            - running
            - done
          title: Status
        counts:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Counts
          description: '{pass, fail, warn, na} at check grain (None in flight).'
        results:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Results
          description: >-
            [{check_id, name, status, message, locators[]}] — the overlay rows,
            built with the pinned ingest's own helpers (None in flight).
        checks_fingerprint:
          type: string
          title: Checks Fingerprint
          description: >-
            Fingerprint of the check set this verify EXECUTED — compare against
            draft_checks_fingerprint; mismatch = stale overlay (blocking flips
            deliberately do NOT change fingerprints).
        created:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created
      type: object
      required:
        - run_id
        - verify_id
        - status
        - checks_fingerprint
      title: SessionRescoreResponse
      description: |-
        One run's verify-only overlay (verify-only-plan §7): the run's LIVE
        verify when one exists (always the newest — one live per run), else its
        latest DONE verify. Error rows never surface here (their narration lives
        in the transcript). Pinned scorecards are untouched — this is the "draft
        re-check" layer the run card renders as a second, visually-distinct row.
        Staleness is ONE client-side comparison: ``checks_fingerprint`` vs the
        snapshot's ``draft_checks_fingerprint``.
    RuleFragmentModel:
      properties:
        id:
          type: string
          title: Id
        text:
          type: string
          title: Text
        source:
          type: string
          enum:
            - base
            - agent
            - user
          title: Source
          default: user
      type: object
      required:
        - id
        - text
      title: RuleFragmentModel
    KnobsModel:
      properties:
        max_turns:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Turns
        timeout_s:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Timeout S
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
      type: object
      title: KnobsModel
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````