> ## Documentation Index > Fetch the complete documentation index at: https://docs.trunk.io/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. includeEstimatedTimeToMerge: type: boolean description: >- When true, the response carries `estimatedTimeToMerge`: when the pull request is expected to merge, computed from the queue ahead of it and the queue's recent test times. 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 - pr_pushed_to description: >- Why the pull request is waiting to enter the queue — how it was submitted, or what sent it back to waiting after it had been admitted. 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. forge: type: string enum: - github - gitlab description: >- The Git hosting service whose account `forgeLogin` names. forgeLogin: type: string description: >- The login (not the display name) of the person who caused the change, on `forge`. Equals `gitHubLogin` for a GitHub account. 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_returned_to_waiting - 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. forge: type: string enum: - github - gitlab description: >- The Git hosting service whose account `forgeLogin` names. forgeLogin: type: string description: >- The login (not the display name) of the person who caused the change, on `forge`. Equals `gitHubLogin` for a GitHub account. 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 - pr_merged_into_other_branch 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. forge: type: string enum: - github - gitlab description: >- The Git hosting service whose account `forgeLogin` names. forgeLogin: type: string description: >- The login (not the display name) of the person who caused the change, on `forge`. Equals `gitHubLogin` for a GitHub account. 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. forge: type: string enum: - github - gitlab description: >- The Git hosting service whose account `forgeLogin` names. forgeLogin: type: string description: >- The login (not the display name) of the person who caused the change, on `forge`. Equals `gitHubLogin` for a GitHub account. 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`. estimatedTimeToMerge: oneOf: - type: object properties: status: type: string const: available computedAt: type: string format: date-time description: >- When the API received the estimate from the merge service; every other time is relative to it, as an RFC 3339 timestamp in UTC. kind: type: string enum: - merge - pending_failure_resolution description: >- What `estimatedAt` is the time of. `merge`: the pull request merges. `pending_failure_resolution`: its tests failed and it is waiting on the pull requests ahead of it, so this is when the outcome is known, an upper bound, not a merge. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing. estimatedAt: type: string format: date-time description: >- The estimated time, per `kind`, as an RFC 3339 timestamp in UTC. estimatedAtState: type: string enum: - on_track - holding - past_typical - past_p95 description: >- How far to trust the time beside it. `on_track`: a forecast that moves earlier as time passes. `holding`: not counting down, because the queue is waiting on a step it treats as instant (such as a test run that can start now) or the time is under a 30-second floor; it does not mean the time is near. `past_typical`: held by a run, this pull request's or one ahead of it, that is past its typical time, so the time is likely an underestimate. `past_p95`: only on `testsFinishAtState`, this pull request's tests are running longer than 95% of the queue's recent passing runs. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing. confidence: type: string enum: - low - medium - high description: >- How much to rely on the estimate. Lower with little recent history, while the pull request waits (more so deep in the queue), and when it is behind a failure, in a bisection, or held by other runs. pullRequestsAhead: type: integer description: >- How many queued pull requests must merge before this one can. waitingForPullRequestNumbers: type: array items: type: integer description: >- For `pending_failure_resolution`, the pull requests ahead whose outcome this one is waiting on. Empty for `merge`. sampleSize: type: integer description: >- How many recent test runs of this queue the estimate is based on. startsTestingAt: type: string format: date-time description: >- When the pull request's next test run is expected to start, as an RFC 3339 timestamp in UTC. Absent once it is testing. startsTestingAtState: type: string enum: - on_track - holding - past_typical - past_p95 description: >- How far to trust `startsTestingAt`, with the values of `estimatedAtState`. Present exactly when `startsTestingAt` is. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing. testsFinishAt: type: string format: date-time description: >- When the pull request's current or next test run is expected to finish passing, including expected restarts, as an RFC 3339 timestamp in UTC. testsFinishAtState: type: string enum: - on_track - holding - past_typical - past_p95 description: >- How far to trust `testsFinishAt`, with the values of `estimatedAtState`; `past_typical` here means this pull request's own run is past `typicalTestDurationSeconds`. Present exactly when `testsFinishAt` is. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing. typicalTestDurationSeconds: type: integer description: >- The queue's typical test run duration: the median of its recent passing runs, in whole seconds rounded down. required: - status - computedAt - kind - estimatedAt - estimatedAtState - confidence - pullRequestsAhead - waitingForPullRequestNumbers - sampleSize title: Available - type: object properties: status: type: string const: unavailable computedAt: type: string format: date-time description: >- When the API received the answer from the merge service, as an RFC 3339 timestamp in UTC. reason: type: string enum: - insufficient_history - not_in_queue - concluded - queue_not_running - unsupported_queue_state - in_bisection - estimate_failed - not_enabled description: >- Why there is no estimate. `insufficient_history`: the queue has too few recent test runs. `not_in_queue`: the pull request is waiting to be admitted. `concluded`: it has merged, failed or been cancelled. `queue_not_running`: the queue is paused or draining. `unsupported_queue_state`: the queue is in a shape the estimate does not model. `in_bisection`: it is in a bisection, and passing returns it to the queue rather than merging it, so only its tests have a time. `estimate_failed`: the estimate could not be computed. `not_enabled`: estimates are not enabled for this queue. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing. sampleSize: type: integer description: >- For `insufficient_history` and `unsupported_queue_state`, how many recent test runs the queue has. samplesRequired: type: integer description: >- For `insufficient_history`, how many recent test runs an estimate needs. startsTestingAt: type: string format: date-time description: >- When the pull request's next test run is expected to start, as an RFC 3339 timestamp in UTC. Absent once it is testing. Only for `in_bisection`. startsTestingAtState: type: string enum: - on_track - holding - past_typical - past_p95 description: >- How far to trust `startsTestingAt`, with the values of `estimatedAtState`. Present exactly when `startsTestingAt` is. Only for `in_bisection`. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing. testsFinishAt: type: string format: date-time description: >- When the pull request's current or next test run is expected to finish passing, including expected restarts, as an RFC 3339 timestamp in UTC. Only for `in_bisection`. testsFinishAtState: type: string enum: - on_track - holding - past_typical - past_p95 description: >- How far to trust `testsFinishAt`, with the values of `estimatedAtState`; `past_typical` here means this pull request's own run is past `typicalTestDurationSeconds`. Present exactly when `testsFinishAt` is. Only for `in_bisection`. New values are added as the queue grows new behavior; treat an unrecognized value as unknown rather than failing. typicalTestDurationSeconds: type: integer description: >- The queue's typical test run duration: the median of its recent passing runs, in whole seconds rounded down. Only for `in_bisection`. required: - status - computedAt - reason title: Unavailable description: >- When the pull request is expected to merge. Only the median estimate is published. Present only when the request set `includeEstimatedTimeToMerge`. 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 description: >- Your organization API token. In the Trunk app, find it under **Settings** → **Developer** → **API Keys**, in the **Organization API token (v1)** section. v2 API keys don't work with the v1 API. The v1 API will be deprecated soon. ````