GitHub: List pull requests

← Pulls operations · Get started

Operation github.pulls_list

Provider route: GET /repos/{owner}/{repo}/pulls. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/github with npm, or alter-sdk-github with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { GitHubIntegration } from "@alter-ai/github";

async function execute(input: Parameters<GitHubIntegration["pulls"]["pullsList"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new GitHubIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.pulls.pullsList(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_github import GitHubIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = GitHubIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.pulls.pulls_list(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.owner	string	Required within parent
path.repo	string	Required within parent
query	object	Optional	Additional keys: not allowed
query.state	string	Optional	Default: open One of: open, closed, all
query.head	string	Optional
query.base	string	Optional
query.sort	string	Optional	Default: created One of: created, updated, popularity, long-running
query.direction	string	Optional	One of: asc, desc
query.per_page	integer	Optional	Default: 30
query.page	integer	Optional	Default: 1

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	array	Root
$[]	Model	Each item	Expand Request reviewers for a pull request — response body

Referenced models: Request reviewers for a pull request — response body

Schemas

11 more schemas are linked from the tables above, on the schema pages.

Request reviewers for a pull request — response body

Field	Type	Presence	Description and constraints
$	object	Root	Pull Request Simple
_links	object	Required within parent
_links.comments	Model	Required within parent	Expand Get a pull request — response body — links html
_links.commits	Model	Required within parent	Expand Get a pull request — response body — links html
_links.html	Model	Required within parent	Expand Get a pull request — response body — links html
_links.issue	Model	Required within parent	Expand Get a pull request — response body — links html
_links.review_comment	Model	Required within parent	Expand Get a pull request — response body — links html
_links.review_comments	Model	Required within parent	Expand Get a pull request — response body — links html
_links.self	Model	Required within parent	Expand Get a pull request — response body — links html
_links.statuses	Model	Required within parent	Expand Get a pull request — response body — links html
active_lock_reason	JSON	Optional
active_lock_reason (anyOf 1)	string	Alternative
active_lock_reason (anyOf 2)	null	Alternative
assignees	array	Optional
assignees[]	Model	Each item	Expand List users — response body — item
author_association	string	Required within parent	How the author is associated with the repository. Known values: COLLABORATOR, CONTRIBUTOR, FIRST_TIMER, FIRST_TIME_CONTRIBUTOR, MANNEQUIN, MEMBER, NONE, OWNER
auto_merge	Model	Required within parent	Expand Get a pull request — response body — auto merge
base	object	Required within parent
base.label	string	Required within parent
base.ref	string	Required within parent
base.repo	Model	Required within parent	Expand List repositories for the authenticated user — response body — item
base.sha	string	Required within parent
base.user	Model	Required within parent	Expand Get an issue — response body — user
body	JSON	Required within parent
body (anyOf 1)	string	Alternative
body (anyOf 2)	null	Alternative
closed_at	JSON	Required within parent
closed_at (anyOf 1)	string	Alternative	Format: date-time
closed_at (anyOf 2)	null	Alternative
comments_url	string	Required within parent	Format: uri
commits_url	string	Required within parent	Format: uri
created_at	string	Required within parent	Format: date-time
diff_url	string	Required within parent	Format: uri
draft	boolean	Optional	Indicates whether or not the pull request is a draft.
head	object	Required within parent
head.label	string	Required within parent
head.ref	string	Required within parent
head.repo	Model	Required within parent	Expand List repositories for the authenticated user — response body — item
head.sha	string	Required within parent
head.user	Model	Required within parent	Expand Get an issue — response body — user
html_url	string	Required within parent	Format: uri
id	JSON	Required within parent
id (anyOf 1)	integer	Alternative	Format: int64
id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
issue_url	string	Required within parent	Format: uri
labels	array	Required within parent
labels[]	object	Each item
labels[].archived_by	JSON	Required within parent
labels[].archived_by (anyOf 1)	JSON	Alternative	The user who archived the label, or `null` if it has not been archived.
labels[].archived_by (anyOf 1) (allOf 1)	Model	All variants apply	Expand List users — response body — item
labels[].archived_by (anyOf 2)	null	Alternative
labels[].color	string	Required within parent
labels[].default	boolean	Required within parent
labels[].description	string	Required within parent
labels[].id	JSON	Required within parent
labels[].id (anyOf 1)	integer	Alternative	Format: int64
labels[].id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
labels[].name	string	Required within parent
labels[].node_id	string	Required within parent
labels[].url	string	Required within parent
locked	boolean	Required within parent
merged_at	JSON	Required within parent
merged_at (anyOf 1)	string	Alternative	Format: date-time
merged_at (anyOf 2)	null	Alternative
milestone	Model	Required within parent	Expand Get an issue — response body — milestone
node_id	string	Required within parent
number	JSON	Required within parent
number (anyOf 1)	integer	Alternative
number (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
patch_url	string	Required within parent	Format: uri
requested_reviewers	array	Optional
requested_reviewers[]	Model	Each item	Expand List users — response body — item
requested_teams	array	Optional
requested_teams[]	Model	Each item	Expand List teams — response body — item
review_comment_url	string	Required within parent
review_comments_url	string	Required within parent	Format: uri
stack	Model	Optional	Expand Get a pull request — response body — stack
state	string	Required within parent
statuses_url	string	Required within parent	Format: uri
title	string	Required within parent
updated_at	string	Required within parent	Format: date-time
url	string	Required within parent	Format: uri
user	Model	Required within parent	Expand Get an issue — response body — user

Referenced models: Get a pull request — response body — auto merge, Get a pull request — response body — links html, Get an issue — response body — milestone, Get an issue — response body — user, Get a pull request — response body — stack, List repositories for the authenticated user — response body — item, List users — response body — item, List teams — response body — item

Get a pull request — response body — auto merge

Field	Type	Presence	Description and constraints
$	JSON	Root
$ (anyOf 1)	object	Alternative	The status of auto merging a pull request.
$ (anyOf 1).commit_message	string	Required within parent	Commit message for the merge commit.
$ (anyOf 1).commit_title	string	Required within parent	Title for the merge commit message.
$ (anyOf 1).enabled_by	Model	Required within parent	Expand List users — response body — item
$ (anyOf 1).merge_method	string	Required within parent	The merge method to use. Known values: merge, squash, rebase
$ (anyOf 2)	null	Alternative

Referenced models: List users — response body — item

Get a pull request — response body — links html

Field	Type	Presence	Description and constraints
$	object	Root	Hypermedia Link
href	string	Required within parent

Policy, approvals and errors

SDK function policy ID: github.pulls_list. Catalog operation: pulls/list. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"X-GitHub-Api-Version": "2026-03-10", "User-Agent": "Alter", "Accept": "application/vnd.github+json"}

Official provider source