Skip to content
TestLookupTestLookup
Search Ctrl K

Search TestLookup

Enter a term to search the local static index.

    Invoke Agent — POST /api/v1/agents/{agent_id}/invoke

    Invoke Agent

    Invoke one agent on a stored test run.

    Endpoint: POST /api/v1/agents/{agent_id}/invoke

    Authentication: Send a signed-in user’s access token in Authorization: Bearer <access token>, or an API key in X-API-Key: <API key>.

    • Your role must be QA engineer or higher.

    Parameters

    Section titled “Parameters”
    NameInRequiredTypeDefaultDescription
    agent_idpathyesstring
    Idempotency-Keyheadernostring or nullClient-generated key (UUID or ULID). The same key with the same request returns the invocation it created (200); with a different request, 422; while the first request is still being handled, 409. Scoped to your user, project, and agent route.
    X-API-Keyheadernostring or nullAPI key, as an alternative to the access token (see Authentication).

    Request body

    Section titled “Request body”
    Content typeBodyRequired
    application/jsonAgentInvokeRequestyes

    Responses

    Section titled “Responses”
    StatusMeaningBody
    200Completed sync result or idempotent replayAgentInvocationResponse (application/json)
    202Successful ResponseAgentInvocationResponse (application/json)
    404Unknown agent or test run; for inline_input, anchor_run_not_found for every wrong anchorNot documented
    409Invocation conflict or request still in flightNot documented
    413inline_input is larger than 262144 bytes (inline_input_too_large)Not documented
    422Invalid input or Idempotency-Key reuseNot documented
    503Synchronous invocation capacity is full; Retry-After is returnedNot documented

    Errors this endpoint returns, read from its source code:

    • 400, with the message “project_id does not match the test run’s project”
    • 403
    • 404, with the message “TestRun not found”
    • 409, with messages such as “A request with this Idempotency-Key is still being handled; retry shortly”, “This agent is already running on the test run under a different request; retry this Idempotency-Key after it finishes”
    • 422, with the message “config_overrides may only tighten the project agent configuration”
    • 503, with the message “All synchronous invocation slots are busy; retry shortly or invoke with mode=async”

    It can also return 401 if your credential is missing or expired, 403 if your credential does not allow this request, and 404 if the item does not exist or you cannot see it. Your role, your project membership and the key’s scope decide what a credential allows. See Errors and retries.

    More details

    Section titled “More details”