Executes the specified agent and returns a non-streaming JSON response with the complete agent output. The agent must be in active status and belong to the specified account. locationId is required in the request body.

Session Management:

  • For the first message in a new session, do not include the executionId in the request payload.

  • The API will return an executionId along with the agent response, which uniquely identifies this conversation session.

  • To continue the conversation within the same session, include the executionId from the previous response in subsequent requests. This allows the agent to maintain conversation context and history across multiple interactions.

http
POST https://services.leadconnectorhq.com/agent-studio/agent/{agentId}/execute

Authorization

NameTypeRequiredExampleDescription
AuthorizationstringYesBearer token generated from the Leadway portal. See Authentication.
VersionstringYes2021-07-28API version.

Path parameters

NameTypeRequiredExampleDescription
agentIdstringYesp1q2r3s4t5u6v7w8x9y0z1a2

Query parameters

NameTypeRequiredExampleDescription
sourcestringNoapi

Body

NameTypeRequiredExampleDescription
messagestringYesHow can you help me with my marketing?Message to send to the agent
executionIdstringNoa1b2c3d4e5f6g7h8i9j0k1l2Unique session identifier that maintains conversational context across multiple interactions within the same agent session. Omit this field for the first message in a new session. Include the executionId returned from the previous response to maintain context in subsequent messages.
inputVariablesobjectNoInput variables to pass to the agent. These should match the input variables defined in the agent configuration.
versionIdstringNob2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4dPublished version ID to execute. If not provided, the latest published production version will be used.
  • attachments (object[]): Attachments for the message

    • type (string, required): Type of attachment Example: image

    • imageUrl (string, required): URL of the image attachment Example: https://example.com/image.png

NameTypeRequiredExampleDescription
locationIdstringYesC2QujeCh8ZnC7al2InWRAccount ID
contactIdstringNocid_abc123def456Contact ID to associate with this execution. When provided, contact data will be hydrated and made available to the agent.

Responses

200 - Agent executed successfully
  • success (boolean, required): Success status Example: True

  • executionId (string, required): Unique session identifier that maintains conversational context across multiple interactions within the same agent session. Use this ID in subsequent requests to continue the conversation. Example: a1b2c3d4e5f6g7h8i9j0k1l2

  • interactionId (string, required): Unique identifier for a single interaction cycle, consisting of one user input and the corresponding agent response. Each message exchange generates a new interactionId. Example: m9n8o7p6q5r4s3t2u1v0w9x8

  • response (string, required): Agent response text Example: I can help you with various tasks...

  • type (string, required): Response type Example: text

  • nextExpectedInput (string, required): Expected input type for next interaction Example: text

  • goalCompletion (boolean, required): When end node is added in the graph, this will be true if the agent reached the end node in the graph Example: False

  • executionStatus (string, required): Execution status Example: completed

  • flowSwitch (boolean, required): Whether flow was switched Example: False

  • attachments (object[], required): Response attachments

  • generativeOutputs (object[], required): Generated outputs

json
{
  "success": true,
  "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
  "interactionId": "m9n8o7p6q5r4s3t2u1v0w9x8",
  "response": "I can help you with various tasks...",
  "type": "text",
  "nextExpectedInput": "text",
  "goalCompletion": false,
  "executionStatus": "completed",
  "flowSwitch": false,
  "attachments": [],
  "generativeOutputs": []
}
400 - Agent is not active or invalid request - locationId is required
401 - Unauthorized
json
{}
403 - User does not have required scopes to execute this agent
404 - Agent not found
422 - Unprocessable Entity
json
{}
500 - Internal Server Error
  • statusCode (number): Example: 500

  • message (string): Example: Internal Server Error

json
{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Example

curl -X POST 'https://services.leadconnectorhq.com/agent-studio/agent/YOUR_agentId/execute' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Version: 2021-07-28' \
  -H 'Content-Type: application/json' \
  -d '{
  "message": "How can you help me with my marketing?",
  "executionId": "a1b2c3d4e5f6g7h8i9j0k1l2",
  "inputVariables": {
    "customerName": "John Doe",
    "orderNumber": "ORD-12345"
  },
  "versionId": "b2b1c1d2-3e4f-5a6b-7c8d-9e0f1a2b3c4d",
  "attachments": [
    {
      "type": "image",
      "imageUrl": "https://example.com/image.png"
    }
  ],
  "locationId": "C2QujeCh8ZnC7al2InWR",
  "contactId": "cid_abc123def456"
}'

Last updated October 26, 2026

Was this page helpful?