> ## Documentation Index > Fetch the complete documentation index at: https://docs.outerlayer.ai/llms.txt > Use this file to discover all available pages before exploring further. # List agent sessions > Returns a filtered, paginated list of agent-coding sessions. Without `sessions.read_team`, actor identities are anonymized and `actor` filters are rejected. When no repo or repoScope is given, results are scoped to the app's dominant repo (the repo with the highest total spend); pass `repo` to pin another repo (an empty `repo` targets sessions with no repository), or `repoScope=all` to list sessions across every repository at once. The response's `repoSelection`, `repositories`, and `hiddenSessions`/`hiddenRepositories` fields report which mode the page resolved to and what a repo pin leaves out. `pr` is dashboard-only for now — this surface has no Postgres reader wired to resolve a PR/MR number to its confirmed-linked sessions, so a `pr` value is rejected rather than silently ignored. ## OpenAPI ````yaml /openapi.yaml get /v1/sessions openapi: 3.0.3 info: contact: email: hello@outerlayer.ai url: https://www.outerlayer.ai description: >- The OuterLayer Gateway API lets you ingest coding-agent sessions and record evidence of work programmatically. Most teams reach it through the `outerlayer` CLI, which calls it for them. Call it directly to build your own integration or to automate what the dashboard does. Versioning: every endpoint is prefixed with `/v1/`. Breaking changes ship under a new version prefix (`/v2/`, etc.) with a 90-day-minimum deprecation window; anything additive lands on the current prefix. Vocabulary: the dashboard calls this API's `app` a **factory** — the unit that owns a set of repositories, the agent sessions worked on them, and the evidence they produce. They are the same entity. The API keeps `app` in its paths, headers, and field names because those are a published contract; only the product surface was renamed. title: OuterLayer Gateway API version: '1.0' servers: - description: Production (OuterLayer Cloud) url: https://api.outerlayer.ai - description: Local dev server (self-hosted gateway) url: http://localhost:9418 security: - AppId: [] BearerAuth: [] tags: - description: >- What a CLI login token can read about its owner without naming a factory, such as the factories they can use. name: Account - description: >- Coding-agent session ingest (outerlayer sync) and content-addressed session images. name: Agents - description: >- Evidence artifacts (screenshots, recordings, reports, logs) emitted as proof of a change and anchored to pull requests. name: Artifacts - description: >- Pass/fail outcomes of checks run in your own CI or compute, anchored to pull requests with the run URL as proof. name: Emitted Results - description: >- The acceptance criteria of a work item, recorded as one list. The Criteria tab, its count and the item status read that list. name: Criteria - description: >- What any agent found wrong about a change under review or about a rule it ran on, recorded on a work item. name: Findings - description: >- Add or remove a source's statement that it is working on an issue or pull request, and read what is currently live. name: Work Items - description: >- What the factory's GitHub App installation lets builds do on each connected repository, and whether each default branch requires a pull request. name: Repositories - description: >- A runner host's heartbeat — its CLI version, slots and last request for work — and the factory's list of hosts with a derived status. name: Hosts - description: Query server feature availability. name: Capabilities - description: Per-model LLM pricing data. Public, unauthenticated. name: Pricing - description: >- Create, list, and revoke factory API keys. Plaintext returned exactly once at creation. name: API Keys - description: >- Factory CRUD — a factory is owned by an organization and is the unit every other resource hangs off. Lets a headless agent provision one without the dashboard. name: Apps - description: >- Agent-coding session list and full transcript reads, with actor-privacy controls for machine keys. name: Sessions - description: >- Per-model token spend and fleet-wide agent behavior tiles, including two-window comparisons. name: Metrics - description: Synced-commit history of the app's `.outerlayer/` context tree. name: Context - description: >- Session→PR attribution: which agent sessions produced which pull requests, and what each attributed PR cost. name: PRs - description: Service health checks. name: Health - description: >- Org member and role administration, authenticated with an org-scoped management API key (`olk_…`) minted in the dashboard's settings. name: Org Management - description: OAuth 2.1 discovery metadata for MCP connector clients. name: OAuth paths: /v1/sessions: get: tags: - Sessions summary: List agent sessions description: >- Returns a filtered, paginated list of agent-coding sessions. Without `sessions.read_team`, actor identities are anonymized and `actor` filters are rejected. When no repo or repoScope is given, results are scoped to the app's dominant repo (the repo with the highest total spend); pass `repo` to pin another repo (an empty `repo` targets sessions with no repository), or `repoScope=all` to list sessions across every repository at once. The response's `repoSelection`, `repositories`, and `hiddenSessions`/`hiddenRepositories` fields report which mode the page resolved to and what a repo pin leaves out. `pr` is dashboard-only for now — this surface has no Postgres reader wired to resolve a PR/MR number to its confirmed-linked sessions, so a `pr` value is rejected rather than silently ignored. operationId: list-sessions parameters: - in: query name: limit required: false schema: default: 25 maximum: 100 minimum: 1 type: integer - in: query name: offset required: false schema: default: 0 maximum: 10000 minimum: 0 nullable: true type: integer - in: query name: repo required: false schema: maxLength: 500 type: string - description: >- Pass "all" to list sessions across every repository instead of pinning to one. Wins over repo when both are present. A separate field from repo, so a repository literally named "all" (or "", the no-repository bucket) stays addressable via repo. in: query name: repoScope required: false schema: description: >- Pass "all" to list sessions across every repository instead of pinning to one. Wins over repo when both are present. A separate field from repo, so a repository literally named "all" (or "", the no-repository bucket) stays addressable via repo. enum: - all type: string - in: query name: branch required: false schema: maxLength: 500 type: string - in: query name: agentType required: false schema: maxLength: 500 type: string - in: query name: model required: false schema: maxLength: 500 type: string - in: query name: workerKind required: false schema: maxLength: 500 type: string - in: query name: q required: false schema: maxLength: 200 type: string - in: query name: actor required: false schema: maxLength: 500 type: string - in: query name: from required: false schema: format: date-time type: string - in: query name: to required: false schema: format: date-time type: string - in: query name: sort required: false schema: default: startedAt enum: - startedAt - cost - errors - turns - steering - toolErrorRate type: string - in: query name: dir required: false schema: default: desc enum: - asc - desc type: string - in: query name: signal required: false schema: enum: - hands-on - denied - tool-errors - provider-errors - clean type: string - in: query name: includeSubagents required: false schema: enum: - '1' type: string - in: query name: origin required: false schema: type: string - in: query name: pr required: false schema: exclusiveMinimum: true minimum: 0 type: integer - in: query name: prRepo required: false schema: minLength: 1 type: string responses: '200': content: application/json: schema: properties: data: properties: actorNames: additionalProperties: type: string type: object actors: items: type: string type: array agentTypes: items: type: string type: array branches: items: type: string type: array hiddenRepositories: description: >- Repositories other than the pinned one holding at least one matching session. 0 outside repoSelection "one". minimum: 0 type: integer hiddenSessions: description: >- Sessions in every repository other than the pinned one — exact even past the repositories list's cap. 0 outside repoSelection "one". minimum: 0 type: integer models: items: type: string type: array originCounts: properties: agent: type: integer interactive: type: integer worker: type: integer required: - interactive - agent - worker type: object repo: type: string repoSelection: description: >- What repo means on this page: "one" — pinned to a single repository (the repo filter's value, or the app's dominant-by-cost repo when none was given); "all" — every repository, requested via repoScope=all; "span" — a trace drill-down that spans repos on its own terms, where repo is meaningless. enum: - one - all - span type: string repositories: description: >- Every repository the app's sessions span under the current non-repo filters, with per-repo session counts; repo "" is the bucket for sessions with no repository. Ordered by count descending, capped at 100 entries — compare repositoriesTotal to detect truncation. Empty in "span" mode. items: properties: repo: type: string sessions: minimum: 0 type: integer required: - repo - sessions type: object type: array repositoriesTotal: description: >- Total distinct repositories under the current non-repo filters, unbounded — greater than the repositories list's length when that list was truncated at its 100-entry cap. 0 in "span" mode. minimum: 0 type: integer scope: enum: - self - team type: string sessions: items: properties: actorId: type: string actorName: type: string agentType: type: string branch: nullable: true type: string contextSourceVerification: enum: - verified - unverified - none type: string costStatus: enum: - complete - partial - unpriced type: string costUsd: nullable: true type: number durationMs: nullable: true type: number endedAt: nullable: true type: string errorCount: type: integer models: items: type: string type: array origin: type: string prOutcomes: items: properties: ciGreen: nullable: true properties: label: type: string score: type: number required: - score - label type: object merged: nullable: true properties: label: type: string score: type: number required: - score - label type: object prNumber: type: integer prUrl: nullable: true type: string reverted: nullable: true properties: label: type: string score: type: number required: - score - label type: object required: - prNumber - prUrl - ciGreen - merged - reverted type: object type: array project: nullable: true type: string rejectedToolCallCount: type: integer sessionId: type: string startedAt: type: string title: nullable: true type: string toolCallCount: type: integer traceId: type: string turnCount: type: integer unpricedModels: items: type: string type: array updatedAt: type: string userTurnCount: type: integer workerKind: nullable: true type: string required: - traceId - sessionId - title - agentType - actorId - workerKind - project - startedAt - endedAt - updatedAt - durationMs - turnCount - toolCallCount - errorCount - userTurnCount - rejectedToolCallCount - costUsd - costStatus - unpricedModels - models - branch type: object type: array total: minimum: 0 type: integer workerKinds: items: type: string type: array required: - repo - scope - repoSelection - total - branches - actors - agentTypes - models - workerKinds - actorNames - repositories - repositoriesTotal - hiddenSessions - hiddenRepositories - sessions type: object required: - data type: object description: A page of agent sessions. '400': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: This key cannot filter sessions by actor. '401': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: Missing or invalid API key. components: securitySchemes: AppId: description: Factory id the request is scoped to. in: header name: X-Outerlayer-App-Id type: apiKey BearerAuth: description: API key (sk_outerlayer_*) scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.