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

# Scan recent workflow runs

> Analyzes the workflows that actually ran in a public repository, not just the ones on the default branch.

Attackers who steal a token often push a workflow that sends secrets to their server, let it run once, then revert the commit or force-push over it. The file disappears from the repository, but the run stays in the Actions tab. This endpoint takes each recent run, fetches the workflow file at the exact commit it ran, analyzes it, and checks whether that commit is still part of its branch.

Costs 10 units of your [rate limit](https://docs.custoden.com/getting-started/rate-limits.md).

## Path parameters

| Name | Type | Description |
| - | - | - |
| `owner` | string | Repository owner |
| `repo` | string | Repository name |

## Query parameters

| Name | Type | Description |
| - | - | - |
| `limit` | integer | Runs to scan, newest first. 1 to 50, default 30 |

## Example

```bash theme={null}
curl "https://api.custoden.com/v1/github/repos/acme/app/runs?limit=20"
```

```json theme={null}
{
  "repository": { "full_name": "acme/app", "default_branch": "main", "url": "https://github.com/acme/app" },
  "runs_scanned": 20,
  "summary": { "critical": 2, "high": 2, "medium": 0, "low": 0, "info": 0, "total": 4 },
  "findings": [
    {
      "rule": "secret-exfiltration",
      "severity": "critical",
      "title": "Secrets sent to an untrusted endpoint",
      "detail": "Step \"Upload report\" uses secrets and contacts http://198.51.99.20, a hardcoded IP address.",
      "remediation": "Remove the step, rotate every secret it could read, and review who added it.",
      "location": { "line": 9, "column": 14, "job": "a", "step": "Upload report" },
      "workflow": { "path": ".github/workflows/security-check.yml", "commit": "a3f9c2e...", "state": "removed" },
      "runs": [18234567890]
    },
    {
      "rule": "workflow-removed-after-run",
      "severity": "high",
      "title": "Workflow ran but is not on the default branch",
      "detail": ".github/workflows/security-check.yml at a3f9c2e ran on 2026-11-10 (branch main) and does not exist on main. That version had access to secrets.",
      "...": "..."
    },
    {
      "rule": "run-commit-rewritten",
      "severity": "high",
      "title": "Run commit was removed from its branch",
      "detail": "Run 18234567890 executed a3f9c2e on \"main\", which is no longer part of that branch. The branch was force-pushed after the run, which also hides what the workflow did.",
      "...": "..."
    }
  ],
  "runs": [
    {
      "id": 18234567890,
      "url": "https://github.com/acme/app/actions/runs/18234567890",
      "workflow_name": "Security Check",
      "workflow_path": ".github/workflows/security-check.yml",
      "event": "push",
      "branch": "main",
      "commit": "a3f9c2e...",
      "actor": "mallory",
      "created_at": "2026-11-10T10:00:00Z",
      "conclusion": "success",
      "from_fork": false,
      "workflow_state": "removed",
      "commit_state": "rewritten",
      "findings": 4
    }
  ],
  "checks": { "branch_history": { "status": "complete", "checked": 6, "total": 6 } },
  "checked_at": "2026-11-16T12:14:02.512Z"
}
```

## Response

| Field | Type | Description |
| - | - | - |
| `repository` | object | `full_name`, `default_branch` and `url` |
| `runs_scanned` | integer | Runs returned by GitHub |
| `summary` | object | Count of findings per severity, plus `total` |
| `findings` | array | Findings across all workflow versions that ran, sorted by severity |
| `runs` | array | One entry per run |
| `checks.branch_history` | object | How many branch and commit pairs were checked for force-pushes |
| `checked_at` | string | ISO 8601 timestamp |

### Finding

Same fields as [workflow findings](https://docs.custoden.com/api-reference/analyze-a-workflow.md#finding), plus:

| Field | Type | Description |
| - | - | - |
| `workflow.path` | string | Workflow file that ran |
| `workflow.commit` | string | Commit the run used |
| `workflow.state` | string | See `workflow_state` below |
| `runs` | integer\[] | IDs of runs that used this workflow version |

For workflow versions that still match the default branch, only `high` and `critical` findings are included. Use [Analyze a workflow](https://docs.custoden.com/api-reference/analyze-a-workflow.md) for the full hardening report on current files.

### Run

| Field | Description |
| - | - |
| `workflow_state` | `current` (identical to the default branch), `modified` (differs from it), `removed` (not on the default branch), `dynamic` (GitHub-managed, such as CodeQL default setup) or `unavailable` (file could not be fetched) |
| `commit_state` | `on_branch`, `rewritten` (commit is no longer in the branch history), `branch_deleted` or `not_checked` |
| `from_fork` | The run used code from a fork, as in pull requests from forks |
| `findings` | Number of findings linked to this run |

Branch deletion after a merged pull request is normal, so `branch_deleted` alone does not produce a finding.

## Rules specific to runs

| Rule | Severity | Meaning |
| - | - | - |
| `workflow-removed-after-run` | high, medium or low | The workflow version that ran is not on the default branch. High when that version has high or critical findings, medium when it had access to secrets |
| `run-commit-rewritten` | high on the default branch, otherwise medium or low | The commit that ran was removed from its branch by a force-push |
| `campaign-workflow-file` | critical or medium | The file name matches one used by a known campaign, such as `shai-hulud-workflow.yml` |
| `campaign-branch` | critical | The run happened on a branch named after Shai-Hulud |

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `invalid_repository` | Owner or repository is not a valid GitHub name |
| 400 | `invalid_limit` | `limit` is not an integer from 1 to 50 |
| 404 | `repository_not_found` | Repository does not exist or is private |
| 429 | `rate_limited` | See [Rate limits](https://docs.custoden.com/getting-started/rate-limits.md) |
| 502 | `upstream_unavailable` | GitHub did not respond |
| 503 | `temporarily_unavailable` | The endpoint is briefly unavailable. Retry after `details.retry_after` seconds |

## Limits

Only public repositories are supported. GitHub keeps run history for 90 days by default, and repository admins can delete runs, so a clean result covers what is still visible.


## OpenAPI

````yaml GET /v1/github/repos/{owner}/{repo}/runs
openapi: 3.1.0
info:
  title: Custoden API
  version: v1
  description: >-
    Free, keyless API for checking open-source packages and GitHub Actions
    workflows.
  contact:
    url: https://github.com/Custoden/docs
servers:
  - url: https://api.custoden.com
security: []
paths:
  /v1/github/repos/{owner}/{repo}/runs:
    get:
      summary: Scan recent workflow runs
      description: Costs 10 rate limit units. Public repositories only.
      operationId: scanRecentRuns
      parameters:
        - name: owner
          in: path
          required: true
          schema:
            type: string
            pattern: ^[A-Za-z0-9_.-]{1,100}$
        - name: repo
          in: path
          required: true
          schema:
            type: string
            pattern: ^[A-Za-z0-9_.-]{1,100}$
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 30
      responses:
        '200':
          description: Run history report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunsReport'
        '400':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Error'
components:
  schemas:
    RunsReport:
      type: object
      required:
        - repository
        - runs_scanned
        - summary
        - findings
        - runs
        - checks
        - checked_at
      properties:
        repository:
          type: object
          properties:
            full_name:
              type: string
            default_branch:
              type: string
            url:
              type: string
              format: uri
        runs_scanned:
          type: integer
        summary:
          $ref: '#/components/schemas/SeveritySummary'
        findings:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/WorkflowFinding'
              - type: object
                properties:
                  workflow:
                    type: object
                    properties:
                      path:
                        type: string
                      commit:
                        type: string
                      state:
                        $ref: '#/components/schemas/WorkflowState'
                  runs:
                    type: array
                    items:
                      type: integer
        runs:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              url:
                type: string
                format: uri
              workflow_name:
                type:
                  - string
                  - 'null'
              workflow_path:
                type: string
              event:
                type: string
              branch:
                type:
                  - string
                  - 'null'
              commit:
                type: string
              actor:
                type:
                  - string
                  - 'null'
              created_at:
                type: string
                format: date-time
              conclusion:
                type:
                  - string
                  - 'null'
              from_fork:
                type: boolean
              workflow_state:
                $ref: '#/components/schemas/WorkflowState'
              commit_state:
                type: string
                enum:
                  - on_branch
                  - rewritten
                  - branch_deleted
                  - not_checked
              findings:
                type: integer
        checks:
          type: object
          properties:
            branch_history:
              $ref: '#/components/schemas/Check'
        checked_at:
          type: string
          format: date-time
    SeveritySummary:
      type: object
      required:
        - critical
        - high
        - medium
        - low
        - info
        - total
      properties:
        critical:
          type: integer
        high:
          type: integer
        medium:
          type: integer
        low:
          type: integer
        info:
          type: integer
        total:
          type: integer
    WorkflowFinding:
      type: object
      required:
        - rule
        - severity
        - title
        - detail
        - remediation
        - location
      properties:
        rule:
          type: string
        severity:
          $ref: '#/components/schemas/Severity'
        title:
          type: string
        detail:
          type: string
        remediation:
          type: string
        location:
          $ref: '#/components/schemas/Location'
    WorkflowState:
      type: string
      enum:
        - current
        - modified
        - removed
        - unavailable
        - dynamic
    Check:
      type: object
      required:
        - status
        - checked
        - total
      properties:
        status:
          type: string
          enum:
            - complete
            - partial
            - skipped
        checked:
          type: integer
        total:
          type: integer
        reason:
          type: string
    ErrorResponse:
      type: object
      required:
        - error
        - request_id
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
        request_id:
          type: string
    Severity:
      type: string
      enum:
        - critical
        - high
        - medium
        - low
        - info
    Location:
      type: object
      required:
        - line
        - column
        - job
        - step
      properties:
        line:
          type: integer
        column:
          type: integer
        job:
          type:
            - string
            - 'null'
        step:
          type:
            - string
            - 'null'
    ErrorBody:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: object
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.