---
title: "Find commits that match the specified query."
method: POST
path: "/filter/commits"
tags: ["filter", "default"]
---

# Find commits that match the specified query.

`POST /filter/commits`

## Request

- Base URL: `{{ server_url }}/v1`
- URL: `{{ server_url }}/v1/filter/commits`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/athenian/apis/title/docs/filter/commits/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- FilterCommitsRequest: Filter for listing commits.
  - `account` integer, required: Session account ID.
  - `date_from` string, date, required: Commits must be made later than or equal to this date.
  - `date_to` string, date, required: Commits must be made earlier than or equal to this date.
  - `timezone` integer: Local time zone offset in minutes, used to adjust `date_from` and `date_to`.
  - `in` RepositoryID[], required: Set of repositories. An empty list raises a bad response 400. Duplicates are automatically ignored.
  - `with_author` DeveloperID[]: A set of developers. An empty list disables the filter and includes everybody. Duplicates are automatically ignored.
  - `with_committer` DeveloperID[]: A set of developers. An empty list disables the filter and includes everybody. Duplicates are automatically ignored.
  - `property` 'bypassing_prs' | 'everything' | 'no_pr_merges', required: Main trait of the commits - the core of the filter. * bypassing_prs: select commits that were pushed without creating a PR * everything: select all the commits matched by the filters * no_pr_merges: select all the commits but PR merges by noreply@github.com
  - `only_default_branch` boolean: Consider only commits that are accessible from the head of the default branch. For example, if your workflow includes PR-ing feature branches, you rebase and merge them and don't delete afterward, `bypassing_prs` will report the commits in those feature branches unless you set `only_default_branch` to `true`.

## Response `200`

Commits that satisfy the specified filters grouped by date.

- CommitsList: List of commits metadata and related user details.
  - `data` Commit[], required
    - `author` CommitSignature, required: Git commit signature. It is guaranteed that `login` and/or `name`&`email` are present.
      - `login` string: User name which uniquely identifies any developer on any service provider. The format matches the profile URL without the protocol part.
      - `name` string: Git signature name.
      - `email` string: Git signature email.
      - `timestamp` string, date-time, required: When the corresponding action happened in UTC.
      - `timezone` number, float, required: Timezone offset of the action timestamp (in hours).
    - `children` string[]: Hashes of the children. Exists only if `property == everything`. Note: the direction is from HEAD to the root, i.e. reversed compared to Git.
    - `committer` CommitSignature, required: Git commit signature. It is guaranteed that `login` and/or `name`&`email` are present.
      - `login` string: User name which uniquely identifies any developer on any service provider. The format matches the profile URL without the protocol part.
      - `name` string: Git signature name.
      - `email` string: Git signature email.
      - `timestamp` string, date-time, required: When the corresponding action happened in UTC.
      - `timezone` number, float, required: Timezone offset of the action timestamp (in hours).
    - `deployments` string[]: Deployments of the commit.
    - `files_changed` integer, required: Number of files changed in this PR.
    - `hash` string, required: Git commit hash.
    - `message` string, required: Commit message.
    - `repository` string, required: Repository name which uniquely identifies any repository in any service provider. The format matches the repository URL without the protocol part. No ".git" should be appended. We support a special syntax for repository sets: "{reposet id}" adds all the repositories from the given set.
    - `size_added` integer, required: Overall number of lines added.
    - `size_removed` integer, required: Overall number of lines removed.
  - `include` object, required: Mentioned GitHub users.
    - `deployments` object: Mapping deployment names to their details.
    - `users` object, required: Mapping user native (e.g., GitHub) login ID -> user details. The users are mentioned in the PRs from "PullRequestSet.data" or in the commits from "FilterCommitsRequest.data".

## Other responses

- `400`: The request is invalid.
- `403`: Calling user is not allowed to access the specified repositories.
- `404`: The specified account does not exist or the user is not a member.
- `422`: The account's installation has not finished yet.

## Changes

- **2023-01-13** `d08637dcd231`: 2 breaking, 1 info
  - the `include/allOf[#/components/schemas/IncludedDeployments]/deployments/additionalProperties/name` response property's maxLength was unset from `100` for the response status `200`
  - the `include/allOf[#/components/schemas/IncludedDeployments]/deployments/additionalProperties/name` response property's minLength was decreased from `1` to `0` for the response status `200`
  - the `include/allOf[#/components/schemas/IncludedDeployments]/deployments/additionalProperties/name` response's property pattern `^([^'\s]| ){1,100}$` was added for the status `200`

[Operation history](https://skmtc.dev/athenian/apis/title/changes/filter/commits/post.md)

---

[API](https://skmtc.dev/athenian/apis/title.md) - [All operations](https://skmtc.dev/athenian/apis/title/llms.txt) - [OpenAPI document](https://skmtc.dev/athenian/apis/title/revisions/110c9f7cffdd?raw)