Implementation:Treeverse LakeFS ListRepositoryRuns

Knowledge Sources	lakeFS lakeFS API Reference
Domains	Data_Quality, REST_API
Last Updated	2026-02-08 00:00 GMT

Overview

Concrete tool for querying action hook execution results provided by the lakeFS REST API, encompassing run listing, run detail retrieval, and individual hook run inspection.

Description

This implementation covers three related Actions API endpoints that together provide a complete view of hook execution history:

1. listRepositoryRuns -- Lists all action runs for a repository, with optional filtering by branch and commit
2. getRun -- Retrieves detailed information about a single action run
3. listRunHooks -- Lists individual hook executions within a specific run

These endpoints enable reviewing the outcome of pre-commit, post-commit, pre-merge, post-merge, and all other event-triggered hook executions.

Usage

Use these APIs when you need to:

• List all hook runs for a repository to get an overview of validation activity
• Filter runs by branch or commit to find specific execution results
• Drill into a specific run to see its details and timing
• Inspect individual hook executions within a run to identify which hook failed
• Build monitoring dashboards or audit reports from hook execution data

Code Reference

Source Location

• Repository: lakeFS
• File: api/swagger.yml (lines 6124-6235)

Signature

listRepositoryRuns

# API Endpoint
GET /api/v1/repositories/{repository}/actions/runs

# Operation ID
operationId: listRepositoryRuns

# Path Parameters
repository: string              # Repository name

# Query Parameters
branch: string                  # Optional: filter by branch name
commit: string                  # Optional: filter by commit ID
after: string                   # Pagination cursor
amount: integer                 # Page size (default 100)

# Response 200: ActionRunList
ActionRunList:
  pagination:
    has_more: boolean
    next_offset: string
    results: integer
    max_per_page: integer
  results:
    - run_id: string            # Unique run identifier
      branch: string            # Branch that triggered the run
      commit_id: string         # Associated commit ID
      event_type: string        # e.g., "pre-commit", "post-merge"
      start_time: string        # ISO 8601 timestamp
      end_time: string          # ISO 8601 timestamp
      status: string            # "completed" or "failed"

getRun

# API Endpoint
GET /api/v1/repositories/{repository}/actions/runs/{run_id}

# Operation ID
operationId: getRun

# Path Parameters
repository: string              # Repository name
run_id: string                  # Run identifier

# Response 200: ActionRun
ActionRun:
  run_id: string
  branch: string
  commit_id: string
  event_type: string
  start_time: string
  end_time: string
  status: string                # "completed" or "failed"

listRunHooks

# API Endpoint
GET /api/v1/repositories/{repository}/actions/runs/{run_id}/hooks

# Operation ID
operationId: listRunHooks

# Path Parameters
repository: string              # Repository name
run_id: string                  # Run identifier

# Query Parameters
after: string                   # Pagination cursor
amount: integer                 # Page size (default 100)

# Response 200: HookRunList
HookRunList:
  pagination:
    has_more: boolean
    next_offset: string
    results: integer
    max_per_page: integer
  results:
    - hook_run_id: string       # Unique hook run identifier
      action: string            # Action name (from YAML)
      hook_id: string           # Hook ID (from YAML)
      status: string            # "completed" or "failed"
      start_time: string        # ISO 8601 timestamp
      end_time: string          # ISO 8601 timestamp

Import

import requests
# or
import lakefs_sdk
from lakefs_sdk.api import actions_api

I/O Contract

Inputs

Name	Type	Required	Description
repository	string (path)	Yes	Name of the repository
run_id	string (path)	Yes (getRun, listRunHooks)	Unique run identifier
branch	string (query)	No	Filter runs by branch name (listRepositoryRuns only)
commit	string (query)	No	Filter runs by commit ID (listRepositoryRuns only)
after	string (query)	No	Pagination cursor for fetching subsequent pages
amount	integer (query)	No	Number of results per page (default: 100)

Outputs

Name	Type	Description
ActionRunList (HTTP 200)	object	Paginated list of action runs with status, timing, and event information
ActionRun (HTTP 200)	object	Detailed information for a single run (getRun only)
HookRunList (HTTP 200)	object	Paginated list of individual hook executions within a run (listRunHooks only)
HTTP 401	error	Unauthorized (missing or invalid credentials)
HTTP 404	error	Repository or run not found

Usage Examples

List All Runs for a Repository

# List recent action runs
curl -X GET \
  "https://lakefs.example.com/api/v1/repositories/my-repo/actions/runs?amount=10" \
  -H "Authorization: Basic $(echo -n 'AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' | base64)"

Filter Runs by Branch

# List runs triggered on the main branch
curl -X GET \
  "https://lakefs.example.com/api/v1/repositories/my-repo/actions/runs?branch=main&amount=25" \
  -H "Authorization: Basic $(echo -n 'AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' | base64)"

Inspect Individual Hook Results Within a Run

# Get hook-level details for a specific run
curl -X GET \
  "https://lakefs.example.com/api/v1/repositories/my-repo/actions/runs/abcd1234-5678-efgh/hooks" \
  -H "Authorization: Basic $(echo -n 'AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' | base64)"

Full Audit Workflow in Python

import lakefs_sdk
from lakefs_sdk.api import actions_api

configuration = lakefs_sdk.Configuration(
    host="https://lakefs.example.com/api/v1",
    username="AKIAIOSFODNN7EXAMPLE",
    password="wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
)

with lakefs_sdk.ApiClient(configuration) as api_client:
    actions = actions_api.ActionsApi(api_client)

    # Step 1: List runs for a specific commit
    runs = actions.list_repository_runs(
        repository="my-repo",
        commit="abc123def456"
    )

    for run in runs.results:
        print(f"Run {run.run_id}: {run.event_type} -> {run.status}")

        # Step 2: If a run failed, drill into hook details
        if run.status == "failed":
            hooks = actions.list_run_hooks(
                repository="my-repo",
                run_id=run.run_id
            )
            for hook in hooks.results:
                if hook.status == "failed":
                    print(f"  FAILED: {hook.action}/{hook.hook_id}")
                    print(f"    Started: {hook.start_time}")
                    print(f"    Ended:   {hook.end_time}")

Related Pages

Implements Principle

• Principle:Treeverse_LakeFS_Hook_Result_Review

Requires Environment

• Environment:Treeverse_LakeFS_LakeFS_Server_Environment

Uses Heuristic

• Heuristic:Treeverse_LakeFS_Retry_Backoff_Configuration