> ## Documentation Index > Fetch the complete documentation index at: https://trunk-4cab4936-mintlify-4e02f272.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Get a submitted pull request from a merge queue. ## OpenAPI ````yaml /openapi.json post /getSubmittedPullRequest openapi: 3.1.0 info: title: Trunk APIs version: 1.0.0 license: name: UNLICENSED servers: - url: https://api.trunk.io/v1 security: [] paths: /getSubmittedPullRequest: post: summary: Get a submitted pull request from a merge queue. requestBody: content: application/json: schema: type: object properties: repo: type: object properties: host: type: string owner: type: string name: type: string required: - host - owner - name targetBranch: type: string pr: oneOf: - type: object properties: number: type: integer minimum: 0 maximum: 4294967295 description: The pull request number. required: - number title: By pull request number - type: object properties: branch: type: string minLength: 1 description: >- The head branch of the pull request. Because a branch name can be reused by many pull requests over time (for example, bots that repeatedly open and merge pull requests from the same branch), the branch is resolved to a single pull request: the open pull request submitted to the merge queue from this branch if one exists, otherwise the most recently closed pull request submitted from this branch, otherwise `404`. Only pull requests that have been submitted to the merge queue are considered. required: - branch title: By head branch description: >- The pull request to look up. Identify it by number or by head branch, but not both. includeTimeline: type: boolean description: >- When true, the response carries `timeline`: every state change the pull request went through, with timestamps and the details of each. Defaults to false. required: - repo - targetBranch - pr responses: '200': description: OK content: application/json: schema: type: object properties: id: type: string description: >- This queue entry's ID. It identifies the entry, not the pull request — a pull request resubmitted after a cancellation gets a new one. state: type: string enum: - not_ready - pending - testing - tests_passed - merged - failed - cancelled - pending_failure description: >- The state of a pull request in the merge queue. See https://docs.trunk.io/merge-queue/using-the-queue/reference#pull-request-states for the full description of each state. readiness: type: object properties: hasImpactedTargets: type: boolean description: >- Whether the set of impacted build/test targets for this PR has been reported. requiresImpactedTargets: type: boolean description: >- Whether the queue is configured to require impacted-target reporting before a PR can start testing. doesBaseBranchMatch: type: boolean description: >- Whether the PR's base branch matches the queue's target branch. gitHubMergeability: type: string enum: - unspecified - in_progress - mergeable - not_mergeable description: >- GitHub's mergeability state for the PR (cached). `unspecified` — not yet known. `in_progress` — GitHub is still computing mergeability. `mergeable` — GitHub reports the PR can be merged. `not_mergeable` — GitHub reports the PR cannot be merged (e.g. merge conflict). required: - requiresImpactedTargets - doesBaseBranchMatch - gitHubMergeability description: >- Readiness signals for a pull request in the merge queue. A PR can start testing when `doesBaseBranchMatch` is true, `gitHubMergeability` is `mergeable`, and (when `requiresImpactedTargets` is true) `hasImpactedTargets` is true. timeline: type: array items: type: object properties: state: type: string enum: - not_ready - pending - testing - tests_passed - merged - failed - cancelled - pending_failure description: The state the pull request entered at this point. timestamp: type: string format: date-time description: >- When the pull request entered `state`, as an RFC 3339 timestamp in UTC. testRun: type: object properties: testRunId: type: string description: >- The ID of the test run. Pass it to `getMergeQueueTestingDetails` for the full check-run breakdown. testBranch: type: string testBranchSha: type: string prNumber: type: number description: >- The number of the pull request the queue opened for this test run. prUrl: type: string description: >- The URL of the test run's pull request — where its checks and logs are. createdAt: type: string format: date-time description: >- When the test run started, as an RFC 3339 timestamp in UTC. status: type: string enum: - in_progress - failed - cancelled - succeeded description: >- The outcome of the test run itself, independent of this pull request's state. requiredStatuses: type: array items: type: string description: >- The checks the test run had to pass for the pull requests in it to merge. requiredStatusesSource: type: string enum: - trunk_config - repo_provider_branch_protection - merge_instance description: Where `requiredStatuses` came from. testedPullRequests: type: array items: type: object properties: prNumber: type: number prUrl: type: string title: type: string state: type: string enum: - not_ready - pending - testing - tests_passed - merged - failed - cancelled - pending_failure description: >- The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one. description: >- Every pull request tested together in this run, including this one. required: - testBranch - testBranchSha - requiredStatuses - testedPullRequests description: >- The merge queue test run this timeline entry refers to. notReady: type: object properties: reason: type: string enum: - user_requested - trunk_admin_requested - api_requested description: >- How the pull request came to be submitted. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing. actor: type: object properties: gitHubLogin: type: string description: >- The GitHub login (not the display name) of the person who caused the change. trunkUserId: type: string description: >- The Trunk user ID of the person who caused the change, when they have one. description: >- Who caused this state change. Absent when the queue itself caused it rather than a person. priorityValue: type: number priorityName: type: string noBatch: type: boolean description: >- Present on `not_ready` entries: the pull request was submitted to the queue. pending: type: object properties: reason: type: string enum: - manual_push_to_target_branch - prerequisite_merge_item_cancelled - prerequisite_merge_item_failed - prerequisite_merge_item_manually_merged - merge_item_now_ready - tests_restarted_by_user - tests_restarted_by_api_request - skip_the_line_interrupted - bisection_required - bisection_test_run_passed description: >- Why the pull request is queued rather than testing. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing. actor: type: object properties: gitHubLogin: type: string description: >- The GitHub login (not the display name) of the person who caused the change. trunkUserId: type: string description: >- The Trunk user ID of the person who caused the change, when they have one. description: >- Who caused this state change. Absent when the queue itself caused it rather than a person. priorityValue: type: number priorityName: type: string usedDefaultPriorityName: type: string prerequisitePullRequests: type: array items: type: object properties: prNumber: type: number prUrl: type: string title: type: string state: type: string enum: - not_ready - pending - testing - tests_passed - merged - failed - cancelled - pending_failure description: >- The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one. description: >- The pull requests ahead of this one that it is queued behind. required: - prerequisitePullRequests description: >- Present on `pending` entries: the pull request is queued, waiting to be tested. testsPassed: type: object properties: reason: type: string enum: - test_run_passed - successor_test_run_passed - passed_by_optimization description: >- How the pull request came to pass. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing. testRunId: type: string testBranchSha: type: string testBranchUrl: type: string batchSize: type: number bisectionId: type: string successorMergeItemId: type: string description: >- The queue entry behind this one whose test run vouched for it, as an `id` — look it up among the `id` fields returned by `getSubmittedPullRequests`. Set when `reason` is `successor_test_run_passed`. otherTestedPullRequests: type: array items: type: object properties: prNumber: type: number prUrl: type: string title: type: string state: type: string enum: - not_ready - pending - testing - tests_passed - merged - failed - cancelled - pending_failure description: >- The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one. waitingFor: type: array items: type: object properties: prNumber: type: number prUrl: type: string title: type: string state: type: string enum: - not_ready - pending - testing - tests_passed - merged - failed - cancelled - pending_failure description: >- The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one. description: >- Pull requests ahead of this one that must merge before it can. required: - testBranchSha - testBranchUrl - batchSize - otherTestedPullRequests - waitingFor pendingFailure: type: object properties: eventualFailureReason: type: string enum: - start_test_run_invalid_event - start_test_run_merge_conflict - start_test_run_config_not_found - start_test_run_config_parsing_failure - >- start_test_run_config_missing_required_statuses - start_test_run_config_bad_required_statuses - start_test_run_config_bad_version - start_test_run_no_required_statuses - start_test_run_retry_exhausted - start_test_run_draft_prs_not_allowed - start_test_run_permissions_block_test_branch - test_run_required_status_failed - test_run_timeout - test_run_failed_by_optimization - github_api_merge_pr_failed - github_api_direct_merge_pr_failed - github_api_rate_limit_exceeded - github_api_branch_protection_unmet - github_api_merge_already_in_progress - github_api_repeated_server_errors - pr_updated_at_merge_time description: >- Why the pull request failed out of the queue. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing. waitingFor: type: array items: type: object properties: prNumber: type: number prUrl: type: string title: type: string state: type: string enum: - not_ready - pending - testing - tests_passed - merged - failed - cancelled - pending_failure description: >- The referenced pull request's own state in the queue. Absent in `testRun.testedPullRequests`, which the queue records without one. failureCausingStatuses: type: array items: type: object properties: name: type: string description: >- The name of the check, as it appears on the pull request. url: type: string description: >- A link to the failing check, when one was recorded. conclusion: type: string description: >- Why the check counted as failed, in SCREAMING_SNAKE_CASE. A GitHub check run contributes its conclusion (`FAILURE`, `TIMED_OUT`, `CANCELLED`, `ACTION_REQUIRED`); a status check contributes its state (`FAILURE`, `ERROR`). Absent on failures recorded before this was captured. required: - name required: - waitingFor - failureCausingStatuses description: >- Present on `pending_failure` entries: this pull request will fail, but the queue is waiting on the pull requests ahead of it to establish the blame. failure: type: object properties: reason: type: string enum: - start_test_run_invalid_event - start_test_run_merge_conflict - start_test_run_config_not_found - start_test_run_config_parsing_failure - >- start_test_run_config_missing_required_statuses - start_test_run_config_bad_required_statuses - start_test_run_config_bad_version - start_test_run_no_required_statuses - start_test_run_retry_exhausted - start_test_run_draft_prs_not_allowed - start_test_run_permissions_block_test_branch - test_run_required_status_failed - test_run_timeout - test_run_failed_by_optimization - github_api_merge_pr_failed - github_api_direct_merge_pr_failed - github_api_rate_limit_exceeded - github_api_branch_protection_unmet - github_api_merge_already_in_progress - github_api_repeated_server_errors - pr_updated_at_merge_time description: >- Why the pull request failed out of the queue. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing. apiFailureMessage: type: string failureCausingStatuses: type: array items: type: object properties: name: type: string description: >- The name of the check, as it appears on the pull request. url: type: string description: >- A link to the failing check, when one was recorded. conclusion: type: string description: >- Why the check counted as failed, in SCREAMING_SNAKE_CASE. A GitHub check run contributes its conclusion (`FAILURE`, `TIMED_OUT`, `CANCELLED`, `ACTION_REQUIRED`); a status check contributes its state (`FAILURE`, `ERROR`). Absent on failures recorded before this was captured. required: - name description: >- The required checks that failed. Populated when `reason` is `test_run_required_status_failed`. blockReasons: type: array items: type: object properties: kind: type: string description: >- Which requirement was unmet: `review_required`, `changes_requested`, `failing_required_check`, `awaiting_required_check`, `behind_base`, `merge_conflict`, `stack_needs_rebase`, or `undetermined`. The fields below are populated per kind. New kinds may be added. have: type: number description: Approvals received, for `review_required`. need: type: number description: Approvals required, for `review_required`. check: type: string description: >- The check's name, for the `*_required_check` kinds. status: type: string description: The check's status, when it has one. state: type: string description: The check's state, when it has one. ontoPrNumber: type: number description: >- For `stack_needs_rebase`, the pull request this one's branch must be rebased onto. required: - kind description: >- The unmet branch-protection requirements. Populated when `reason` is `github_api_branch_protection_unmet`. conflictCulprit: type: object properties: prNumber: type: number prUrl: type: string sha: type: string type: type: string enum: - queue_pr - base_branch - stacked_pr required: - type description: >- The earlier queue entry a merge conflict was traced to. Identified asynchronously, so it is absent until the investigation finishes, and permanently absent when no single entry was to blame. required: - failureCausingStatuses - blockReasons cancellation: type: object properties: reason: type: string enum: - user_requested - trunk_admin_requested - pr_closed - pr_pushed_to - pr_base_branch_changed - pr_converted_to_draft - not_ready_timeout_expired - stacked_pr_member_pushed_to - stacked_pr_member_closed - stacked_pr_member_merged - stacked_pr_member_base_branch_changed - stacked_pr_stack_changed - stacked_pr_group_cancelled_at_merge_time description: >- Why the pull request was removed from the queue. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing. actor: type: object properties: gitHubLogin: type: string description: >- The GitHub login (not the display name) of the person who caused the change. trunkUserId: type: string description: >- The Trunk user ID of the person who caused the change, when they have one. description: >- Who caused this state change. Absent when the queue itself caused it rather than a person. merged: type: object properties: reason: type: string enum: - merge_graph_merge - merge_graph_direct_merge - manual_merge description: >- How the pull request was merged. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing. actor: type: object properties: gitHubLogin: type: string description: >- The GitHub login (not the display name) of the person who caused the change. trunkUserId: type: string description: >- The Trunk user ID of the person who caused the change, when they have one. description: >- Who caused this state change. Absent when the queue itself caused it rather than a person. description: >- One state change in a pull request's life in the merge queue, with the details of why it happened. At most one of the per-state detail objects is present, matching `state`. `testRun` is independent of those and accompanies any entry that refers to a test run — a `testing` entry, and a `failed` or `pending_failure` entry whose cause was a test. description: Present only when the request set `includeTimeline`. stateChangedAt: type: string priorityValue: type: number priorityName: type: string usedDefaultPriorityName: type: string skipTheLine: type: boolean forceEnqueued: type: boolean isCurrentlySubmittedToQueue: type: boolean prNumber: type: number prTitle: type: string prSha: type: string prBaseBranch: type: string prAuthor: type: string verifiedByTestRun: type: - object - 'null' properties: testRunId: type: string description: >- The ID of the test run that caused this pull request to be merged. testBranchSha: type: string description: >- The commit SHA of the head of the test branch for this test run. required: - testRunId - testBranchSha description: >- The merge queue test run that verified this pull request before it was merged. For an optimistically merged pull request, this is the test run of the pull request behind it whose passing caused the optimistic merge. Null if the pull request is not merged, or was merged without a verifying test run (e.g. force merged). required: - stateChangedAt - priorityValue - priorityName - skipTheLine - forceEnqueued - isCurrentlySubmittedToQueue - prNumber - prTitle - prSha - prBaseBranch - prAuthor - verifiedByTestRun '400': description: Bad Request content: application/plain-text: schema: type: string '401': description: Unauthorized content: application/plain-text: schema: type: string '404': description: Not Found content: application/plain-text: schema: type: string '500': description: Internal Server Error content: application/plain-text: schema: type: string security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-token ````