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

# Pipelines API: Query CI/CD Pipeline Run History

> Retrieve ingested pipeline run records and individual run details sourced automatically from GitHub Actions and GitLab CI webhook events.

The pipelines API provides read-only access to CI/CD run history that the platform ingests automatically from your connected source control providers. When a pipeline run completes in GitHub Actions or GitLab CI, a webhook payload is delivered to the platform and stored as a structured run record. You can query this history to surface build trends, correlate deploys with incidents, or feed data into reporting dashboards — no manual data entry required.

All requests require a Bearer token in the `Authorization` header.

<Note>
  Pipeline runs are created exclusively through GitHub and GitLab webhook ingestion. The API does not expose endpoints for creating, updating, or deleting run records.
</Note>

***

## List pipeline runs

`GET https://your-api-domain.com/api/v1/pipelines`

Returns a paginated list of all ingested pipeline run records, ordered by start time descending (most recent first).

### Query parameters

<ParamField query="page" type="number" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="limit" type="number" default="25" placeholder="1-100">
  Number of records to return per page.
</ParamField>

<ParamField query="status" type="string">
  Filter by run status. Accepted values: `success`, `failure`, `cancelled`, `in_progress`.
</ParamField>

<ParamField query="provider" type="string">
  Filter by source provider. Accepted values: `github`, `gitlab`.
</ParamField>

<ParamField query="repository" type="string" placeholder="org/repo-name">
  Filter runs to a specific repository, in `owner/repo` format.
</ParamField>

<ParamField query="branch" type="string" placeholder="main">
  Filter runs triggered from a specific branch.
</ParamField>

### Response fields

<ResponseField name="runs" type="object[]" required>
  Array of pipeline run summary objects.

  <Expandable title="run properties">
    <ResponseField name="id" type="string" required>
      Unique identifier for the run record.
    </ResponseField>

    <ResponseField name="provider" type="string" required>
      Source provider: `github` or `gitlab`.
    </ResponseField>

    <ResponseField name="repository" type="string" required>
      Repository in `owner/repo` format.
    </ResponseField>

    <ResponseField name="branch" type="string" required>
      Branch the pipeline ran against.
    </ResponseField>

    <ResponseField name="commitSha" type="string" required>
      Full SHA of the commit that triggered the run.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Final run status: `success`, `failure`, `cancelled`, or `in_progress`.
    </ResponseField>

    <ResponseField name="startedAt" type="string" required>
      ISO 8601 timestamp when the run began.
    </ResponseField>

    <ResponseField name="finishedAt" type="string">
      ISO 8601 timestamp when the run completed. `null` if still in progress.
    </ResponseField>

    <ResponseField name="durationSeconds" type="number">
      Total run duration in seconds. `null` if still in progress.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object" required>
  Pagination metadata.

  <Expandable title="pagination properties">
    <ResponseField name="page" type="number" required>
      Current page number.
    </ResponseField>

    <ResponseField name="limit" type="number" required>
      Records per page.
    </ResponseField>

    <ResponseField name="total" type="number" required>
      Total number of matching records across all pages.
    </ResponseField>

    <ResponseField name="totalPages" type="number" required>
      Total number of pages.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://your-api-domain.com/api/v1/pipelines?limit=25&status=failure&provider=github' \
    --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    limit: '25',
    status: 'failure',
    provider: 'github',
  });

  const response = await fetch(
    `https://your-api-domain.com/api/v1/pipelines?${params}`,
    {
      headers: { Authorization: 'Bearer YOUR_TOKEN' },
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://your-api-domain.com/api/v1/pipelines',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
      params={
          'limit': 25,
          'status': 'failure',
          'provider': 'github',
      },
  )
  data = response.json()
  ```
</CodeGroup>

***

## Get a pipeline run

`GET https://your-api-domain.com/api/v1/pipelines/:id`

Returns the full detail record for a single pipeline run, including individual job or stage results if available in the webhook payload.

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the pipeline run record.
</ParamField>

### Response fields

<ResponseField name="id" type="string" required>
  Unique run record identifier.
</ResponseField>

<ResponseField name="provider" type="string" required>
  Source provider: `github` or `gitlab`.
</ResponseField>

<ResponseField name="repository" type="string" required>
  Repository in `owner/repo` format.
</ResponseField>

<ResponseField name="branch" type="string" required>
  Branch the pipeline ran against.
</ResponseField>

<ResponseField name="commitSha" type="string" required>
  Full SHA of the triggering commit.
</ResponseField>

<ResponseField name="commitMessage" type="string">
  The commit message associated with the triggering commit.
</ResponseField>

<ResponseField name="triggeredBy" type="string">
  Username or actor that triggered the pipeline.
</ResponseField>

<ResponseField name="status" type="string" required>
  Final run status: `success`, `failure`, `cancelled`, or `in_progress`.
</ResponseField>

<ResponseField name="startedAt" type="string" required>
  ISO 8601 timestamp when the run began.
</ResponseField>

<ResponseField name="finishedAt" type="string">
  ISO 8601 timestamp when the run completed. `null` if still in progress.
</ResponseField>

<ResponseField name="durationSeconds" type="number">
  Total run duration in seconds.
</ResponseField>

<ResponseField name="jobs" type="object[]">
  Individual job or stage results, if provided by the webhook payload.

  <Expandable title="job properties">
    <ResponseField name="name" type="string" required>
      Job or stage name.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Job-level status: `success`, `failure`, `skipped`, or `cancelled`.
    </ResponseField>

    <ResponseField name="durationSeconds" type="number">
      Duration for this individual job in seconds.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rawPayload" type="object">
  The original webhook payload received from the provider, stored for auditability.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://your-api-domain.com/api/v1/pipelines/run_abc123 \
    --header 'Authorization: Bearer YOUR_TOKEN'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://your-api-domain.com/api/v1/pipelines/run_abc123',
    {
      headers: { Authorization: 'Bearer YOUR_TOKEN' },
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://your-api-domain.com/api/v1/pipelines/run_abc123',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
  )
  data = response.json()
  ```
</CodeGroup>