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

# List commits

> Recorded commits with available summaries, attribution, branch metadata and productivity estimates.

Returns recorded commits from readable repositories, selecting configured development/default branches unless another branch mode is supplied. Requires workspace Read and repository read access. Coding-time estimates are omitted without Productivity permission or an available estimate.

> [!NOTE]
>
> Follow `nextPageToken` even when a page is short or empty. Only an absent token means the feed is exhausted. Results are live, not a snapshot export.

## Authorization

**Authorization** `string` *required*

`Bearer <key>`. See [Authentication](https://docs.macroscope.com/api#authentication).

## Path parameters

**workspaceType** `string` *required*

`GITHUB_ORGANIZATION` or `GITHUB_USER`.

**workspaceId** `string` *required*

Numeric GitHub ID of the organization or user. Must match the key's workspace.

## Query parameters

Repeat list parameters. Omitted lists apply no additional filter.

**repositoryIds** `string[]`

Repository identifiers. Omit for all readable active repositories. Every explicitly selected repository must be readable.

**startTime** `string`

Inclusive beginning of the effective commit date interval (RFC 3339). Omit for no lower bound; this does not default to a reporting period.

**endTime** `string`

Inclusive end of the effective commit date interval (RFC 3339). Omit for no upper bound. Effective dates need not match the original `authoredAt` or `committedAt` timestamp.

**githubAuthorIds** `string[]`

Positive GitHub commit-author IDs, encoded as decimal int64 strings.

**labels** `string[]`

Nonempty commit classification labels to match.

**areaIds** `string[]`

Area identifiers (UUIDs) from [List areas](https://docs.macroscope.com/api-reference/endpoint/list-areas.md).

**search** `string`

Nonempty semantic search text. Selects the top 25 candidates **before** other filters, independently of `pageSize`. This is not exhaustive substring search; fewer than 25 matches can remain after filtering.

**filePaths** `string[]`

Exact paths or supported globs such as `*.go` or `src/**/*.ts`. Paths must be nonempty. Patterns containing `***` are rejected.

**branchMode** `string` (default: DEVELOPMENT\_BRANCHES)

`DEVELOPMENT_BRANCHES` selects configured development/default branches; `ALL_BRANCHES` selects any branch; `RELEASE_BRANCHES_AND_TAGS` selects release-associated commits; `FEATURE_BRANCHES` selects non-development branches; `LANDED` selects landed shipped units, including on continuation pages. Omitted or `COMMIT_BRANCH_MODE_UNSPECIFIED` selects development/default branches. Landed does not mean deployed.

**pageSize** `integer` (default: 50)

Maximum commits per page, 1–200.

**pageToken** `string`

Opaque `nextPageToken`, bound to the workspace, operation and normalized filters. Expires after 24 hours. Repeat the original filters; `pageSize` may change. Invalid or mismatched tokens return `400`; restart without a token.

## Response

**commits** `object[]`

Matching commits in deterministic feed order. A short or empty page can still have a continuation.

**properties**

**name** `string`

Resource name: `workspaces/{workspaceType}/{workspaceId}/repositories/{repositoryId}/commits/{hash}`.

**hash** `string`

Git commit hash, unique within the repository.

**repositoryId** `string`

Repository identifier.

**repositoryDisplayName** `string`

Repository name in owner/name form.

**message** `string`

Original Git commit message.

**description** `string`

Macroscope-generated description, omitted if not yet available.

**parentHashes** `string[]`

Parent commit hashes.

**authorDisplayName** `string`

Git author display name. No email address is exposed.

**githubAuthorId** `string`

GitHub author ID (int64), when known.

**githubAuthorLogin** `string`

GitHub author login, when known.

**authoredAt** `string`

Original Git author timestamp (RFC 3339), when recorded.

**committedAt** `string`

Original Git committer timestamp (RFC 3339), when recorded.

**githubUrl** `string`

Link to the commit on GitHub.

**labels** `string[]`

Commit classification labels.

**userFacingChangeDescription** `string`

Description of behavior changes, when available.

**pullRequestNumber** `string`

Associated GitHub pull-request number (int64), when known.

**estimatedPersonMinutes** `integer`

Estimated coding time in person-minutes; absent without Productivity or an estimate.

**squashEstimatedPersonMinutes** `integer`

Squash-aware coding-time estimate in person-minutes; absent without Productivity or an estimate.

**originatingRefName** `string`

Observed originating branch ref; omitted when unavailable.

**releaseRefName** `string`

Originating release branch or tag ref, when available.

**releasedAt** `string`

Release timestamp (RFC 3339), when available.

**inDevelopmentBranch** `boolean`

Whether the commit belongs to a configured development branch. Omitted when false.

**nextPageToken** `string`

Follow this opaque continuation even on a short or empty page; absent only when the feed is exhausted.

Default scalars and empty lists are omitted from JSON. Missing optional descriptions, identifiers or estimates mean unavailable, not zero activity. See [shared errors and limits](https://docs.macroscope.com/api#errors).

```bash cURL theme={null}
curl --get https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/commits \
  -H "Authorization: Bearer $MACROSCOPE_API_KEY" \
  --data-urlencode "branchMode=LANDED" \
  --data-urlencode "pageSize=50"
```

```json 200 theme={null}
{
  "commits": [
    {
      "name": "workspaces/GITHUB_ORGANIZATION/12345678/repositories/123456789/commits/0123456789abcdef0123456789abcdef01234567",
      "hash": "0123456789abcdef0123456789abcdef01234567",
      "repositoryId": "123456789",
      "repositoryDisplayName": "acme/backend",
      "message": "Handle cancellation during processing",
      "authorDisplayName": "Example Developer",
      "committedAt": "2026-10-01T12:00:00Z",
      "inDevelopmentBranch": true
    }
  ]
}
```


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