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

# Cancel a WebMCP invocation

> Request best-effort cancellation and return the current handle.

See the [WebMCP guide](/docs/sessions/webmcp) for SDK examples and invocation lifecycle details.


## OpenAPI

````yaml openapi.json POST /api/session/{id}/webmcp/invocations/{invocationId}/cancel
openapi: 3.0.1
info:
  title: Hyperbrowser API
  version: 1.0.0
servers:
  - url: https://api.hyperbrowser.ai
    description: Production server
security: []
paths:
  /api/session/{id}/webmcp/invocations/{invocationId}/cancel:
    post:
      summary: Cancel a WebMCP invocation
      description: >-
        Request best-effort cancellation and return the current handle.
        Completion can win the race. This does not roll back page side effects.
        Continue result reads if still pending. Requires an active session
        created with enableWebMcp: true and an API key with
        browser.sessions.update permission.
      operationId: cancelWebmcpInvocation
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Session ID.
        - name: invocationId
          in: path
          required: true
          schema:
            type: string
            pattern: ^[a-f0-9]{24}$
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebMCPInvocation'
        '400':
          description: Invalid request or tool reference.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebMCPErrorResponse'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebMCPErrorResponse'
        '403':
          description: Insufficient API key permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebMCPErrorResponse'
        '404':
          description: >-
            Session, tool, or invocation not found. Expired handles return
            invocation_not_found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebMCPErrorResponse'
        '409':
          description: >-
            Session is stopped, unavailable, or was not created with WebMCP
            enabled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebMCPErrorResponse'
        '429':
          description: >-
            Rate limit reached; too_many_invocations indicates 16 active
            invocations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebMCPErrorResponse'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebMCPErrorResponse'
        '502':
          description: WebMCP service unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebMCPErrorResponse'
        '504':
          description: >-
            Request timed out. For invocation requests, outcome_unknown means
            the tool may have acted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebMCPErrorResponse'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: javascript
          label: Node.js
          source: |-
            import { Hyperbrowser } from "@hyperbrowser/sdk";

            const client = new Hyperbrowser();

            const invocation = await client.sessions.webmcp.cancel(
              "session-id", "invocation-id"
            );
        - lang: python
          label: Python
          source: >-
            from hyperbrowser import Hyperbrowser


            client = Hyperbrowser()


            invocation = client.sessions.webmcp.cancel("session-id",
            "invocation-id")
components:
  schemas:
    WebMCPInvocation:
      type: object
      properties:
        invocationId:
          type: string
          pattern: ^[a-f0-9]{24}$
        toolRef:
          type: string
        status:
          type: string
          enum:
            - running
            - awaiting_submission
            - completed
            - error
            - canceled
            - outcome_unknown
        cancellationRequested:
          type: boolean
          description: Whether cancellation was requested, regardless of the final outcome.
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          description: Nominal terminal-result expiry. Results may be evicted earlier.
          format: date-time
        result:
          $ref: '#/components/schemas/WebMCPInvokeResult'
        error:
          $ref: '#/components/schemas/WebMCPInvocationError'
      required:
        - invocationId
        - toolRef
        - status
        - cancellationRequested
        - createdAt
      description: >-
        Ephemeral, session-local handle. Pending states have no result or error.
        A terminal handle may contain a result or an error. Lost on receiver
        restart, session rebind, or browser shutdown. At most 16 active and 64
        retained; terminal results expire after 10 minutes and may be evicted
        sooner.
    WebMCPErrorResponse:
      type: object
      properties:
        message:
          type: string
        error:
          type: string
        code:
          type: string
        invocationId:
          type: string
      description: >-
        HTTP failure. Structured WebMCP errors include message and code; other
        session or validation errors may only include error or message. An
        outcome_unknown error may include an invocationId for later retrieval.
    WebMCPInvokeResult:
      type: object
      properties:
        invocationId:
          type: string
          description: Handle for subsequent result reads or cancellation, when provided.
        status:
          type: string
          enum:
            - completed
            - error
            - canceled
            - awaiting_submission
        output:
          description: >-
            Any JSON value returned by the page, including null. Absent if
            unavailable or withheld for exceeding the output limit.
        errorText:
          type: string
        outputBytes:
          type: integer
          minimum: 0
          description: Byte length of the original JSON output.
        outputTruncated:
          type: boolean
          description: True when output exceeds 1 MiB. Full output is withheld.
        outputPreview:
          type: string
          description: >-
            At most 4096 UTF-8 bytes of the oversized output; may be incomplete
            JSON.
        untrustedContent:
          type: boolean
        durationMs:
          type: integer
          minimum: 0
      required:
        - status
        - outputBytes
        - untrustedContent
        - durationMs
    WebMCPInvocationError:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

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