> ## 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. # Read an automation's run log > Lists the runs of one automation, newest first: a custom automation by its id, or a built-in automation by its kind, such as `label-build`. Each run has its issue, its result (`built`, `waiting`, `skipped`, `failed`, `filed`, `refused`, `sent` or `reviewed`), a `reason` and the person who opened the issue or added the label. A run of a built-in automation that acts on pull requests (`merge-conflict`, `failed-check`, `review-comment` or `code-review`) also has its `pullRequest`, its `workItem` and, for a code review that could not run, its `runnerReason`. `before` reads runs older than a time, to page back; send the last run's `createdAt` and `id` as `before` and `beforeId`. Runs are kept for 90 days. ## OpenAPI ````yaml /openapi.yaml get /v1/apps/{appId}/automation-runs 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: >- The route a fleet machine asks for its next managed build on. A fleet machine is a machine OuterLayer operates. name: Fleet - description: >- The CLI version a gateway names to its runners, set with the gateway's runner version key. name: Runner version - 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: >- Find, file and edit the issue a spec lives in, through OuterLayer, with no tracker credential on the caller's side. name: Specs - 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: >- The runs of a schedule automation: a runner claims a run, asks for its read token and ends it, and the run's agent reports each issue it found or that it found nothing. name: Schedule runs - 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/apps/{appId}/automation-runs: get: tags: - Apps summary: Read an automation's run log description: >- Lists the runs of one automation, newest first: a custom automation by its id, or a built-in automation by its kind, such as `label-build`. Each run has its issue, its result (`built`, `waiting`, `skipped`, `failed`, `filed`, `refused`, `sent` or `reviewed`), a `reason` and the person who opened the issue or added the label. A run of a built-in automation that acts on pull requests (`merge-conflict`, `failed-check`, `review-comment` or `code-review`) also has its `pullRequest`, its `workItem` and, for a code review that could not run, its `runnerReason`. `before` reads runs older than a time, to page back; send the last run's `createdAt` and `id` as `before` and `beforeId`. Runs are kept for 90 days. operationId: list-automation-runs parameters: - in: path name: appId required: true schema: format: uuid type: string - description: >- A custom automation's id, or the kind of a built-in automation, such as `label-build`. in: query name: automation required: true schema: description: >- A custom automation's id, or the kind of a built-in automation, such as `label-build`. pattern: >- ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[a-zA-Z][a-zA-Z0-9-]{0,63})$ type: string - description: The most runs to return. in: query name: limit required: false schema: default: 50 description: The most runs to return. maximum: 100 minimum: 1 type: integer - description: >- Return only runs older than this time, or at this time with an id below `beforeId`. in: query name: before required: false schema: description: >- Return only runs older than this time, or at this time with an id below `beforeId`. format: date-time type: string - description: >- The id of the last run of the previous page. With `before`, it keeps runs that share that time from being skipped. in: query name: beforeId required: false schema: description: >- The id of the last run of the previous page. With `before`, it keeps runs that share that time from being skipped. format: uuid type: string responses: '200': content: application/json: schema: properties: data: items: properties: actor: description: >- The person who opened the issue or added the label. `null` when the run did not look. nullable: true properties: kind: description: >- `member` when the person matches a member of the team. enum: - member - outside type: string name: nullable: true type: string required: - kind - name type: object alertKey: description: >- The alert key of a webhook automation's run. `null` for a Refused run, which stores no alert. nullable: true type: string createdAt: type: string detail: description: >- The values the reason's sentence needs. It never holds an error message or free text. properties: attempt: description: >- The attempt number of a build that Fix failed checks started. minimum: 1 type: integer baseBranch: description: The branch the conflict is with. maxLength: 255 type: string commit: description: The commit a code review covers. pattern: ^[0-9a-f]{40}$ type: string limit: type: integer memberName: type: string notSent: description: >- Why comments of a GitHub review did not go to the agent, with a count for each reason. items: properties: count: minimum: 1 type: integer reason: enum: - aside - no_mention - comment_review_no_mention type: string required: - reason - count type: object type: array problems: description: The problems a code review found. minimum: 0 type: integer refusal: description: >- The code the gateway gave when it refused the claim. enum: - pull_request_from_fork - pull_request_on_default_branch - pull_request_ambiguous - pull_request_repository_not_connected - repository_not_reachable - branch_claimed_elsewhere type: string sent: description: >- The comments of a GitHub review that went to the agent. minimum: 0 type: integer step: type: string total: description: The comments of a GitHub review. minimum: 0 type: integer type: object id: format: uuid type: string issue: description: >- `null` for a run that reached no tracker, such as a Refused one. nullable: true properties: key: description: >- `null` for a run that filed no issue, such as one the tracker refused. nullable: true type: string title: nullable: true type: string tracker: type: string url: nullable: true type: string required: - tracker - key - url - title type: object issues: description: >- The issues a schedule run reported, and what became of each. items: properties: key: description: >- The tracker key of the filed issue. For `still_open` and `closed_no_fix`, the key of the earlier issue of the topic. `null` for an issue that was not filed and names no earlier issue. nullable: true type: string outcome: enum: - reported - filing - filed - still_open - closed_no_fix - held_back - over_limit - tracker_refused type: string x-extensible-enum: - reported - filing - filed - still_open - closed_no_fix - held_back - over_limit - tracker_refused title: type: string topic: type: string tracker: nullable: true type: string trackerAnswer: description: >- For `tracker_refused`, why OuterLayer filed nothing: what the tracker said when it refused, or OuterLayer's own reason, such as where to look for an issue the tracker may have made. nullable: true type: string url: nullable: true type: string workItemId: description: The work item of the filed issue. format: uuid nullable: true type: string required: - title - topic - outcome - tracker - key - url - trackerAnswer - workItemId type: object type: array nothingReason: description: The reason a schedule run gave for finding nothing. nullable: true type: string pullRequest: description: >- The pull request a built-in pull request automation decided on. `null` for any other run. nullable: true properties: headSha: description: The commit the decision was about. nullable: true type: string number: type: integer repository: description: The pull request's repository, as `owner/repo`. type: string title: description: >- `null` when OuterLayer no longer stores the pull request. nullable: true type: string required: - repository - number - title - headSha type: object reason: description: >- Why the run ended as it did. A code from the run log list in `@outerlayer/automations`. A new code is not a breaking change, so a client that reads a code it does not know shows it as it is. type: string repository: description: The repository a schedule run reads. type: string result: enum: - built - waiting - skipped - failed - filed - refused - sent - reviewed - pending - running - found - nothing type: string runnerReason: description: >- The runner's reason for a code review that could not run, on one line and at most 200 characters. nullable: true type: string session: description: >- The session of a schedule run. `null` while no session has reached the gateway. nullable: true properties: id: type: string traceId: nullable: true type: string required: - id - traceId type: object startedBy: description: >- What started a schedule automation's run. Not set for any other run. properties: kind: description: >- `schedule` for a due time. `run_now` when a member started the run. enum: - schedule - run_now type: string name: description: >- The member who started a Run now. `null` for a due time. nullable: true type: string required: - kind - name type: object timeLimitSeconds: description: How long a schedule run may take. type: integer trackerAnswer: description: >- What the tracker said when it refused to create the issue. type: string waiting: description: >- Why no runner has taken a schedule run. A pending run carries the reason that holds now. A run that failed at the deadline carries the reason that held when it failed. `null` for any other schedule run. nullable: true properties: hosts: description: >- The runners that take the run, each with its state. Set only for `runners-unavailable`. items: properties: host: description: The runner's name. type: string state: description: Why the runner takes no new work. enum: - draining - restarting - holding-for-update - blocked - low-disk - outdated type: string version: description: >- For `outdated`, the version the runner runs. type: string required: - host - state type: object type: array reason: description: >- `no-runner`: no runner of the factory has checked in within three of its poll intervals. `no-taker`: a runner is running, but none takes the runs of this repository. `runners-unavailable`: the runners that take the run are all unavailable. `waiting-for-runner`: a runner that takes the run is available. enum: - no-runner - no-taker - runners-unavailable - waiting-for-runner type: string required: - reason type: object workItem: description: >- The work item the decision was about. `null` for a run that names none. nullable: true properties: id: format: uuid type: string number: nullable: true type: integer required: - id - number type: object required: - id - createdAt - issue - result - reason - actor - detail type: object type: array required: - data type: object description: The runs. '400': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: >- `automation` is neither an id nor a kind, `limit` is not 1 to 100, or `before` is not a time (`invalid_query`). '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. '403': content: application/json: schema: properties: error: properties: code: type: string message: type: string required: - code - message type: object required: - error type: object description: Caller lacks 'factory.read' permission. 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.