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

# Agent tool execute kql



## OpenAPI

````yaml /api-reference/openapi.json post /api/v2/workspaces/{workspaceId}/agent/tools/kql/query
openapi: 3.1.1
info:
  title: ContraForce API
  description: ContraForce platform API for security operations management.
  version: '2.0'
servers: []
security: []
tags:
  - name: Incidents
  - name: Gamebooks
  - name: Data sources
  - name: Service tickets
  - name: Investigation
  - name: agent-tools
  - name: Cross-workspace incidents
  - name: Cross-workspace gamebooks
  - name: Cross-workspace data sources
  - name: Webhooks
  - name: Service accounts
  - name: Users
  - name: Azure resources
paths:
  /api/v2/workspaces/{workspaceId}/agent/tools/kql/query:
    post:
      tags:
        - agent-tools
      summary: Agent tool execute kql
      operationId: v2-agent-tool-execute-kql
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentToolKqlQueryRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfAgentToolKqlQueryResult'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
components:
  schemas:
    AgentToolKqlQueryRequest:
      type: object
      properties:
        query:
          type:
            - 'null'
            - string
          description: >-
            KQL query to execute against the workspace's Log Analytics
            workspace. Ground the query in the real schema first by calling
            list-kql-tables and get-kql-table-columns — queries against
            non-existent tables or columns return a clear error. Prefer
            narrowly-scoped queries (specific table, time range, project clause)
            over broad scans to keep results inside the row cap.
        max_rows:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
            - 'null'
            - integer
            - string
          description: >-
            Optional row cap. Defaults to 50 server-side; values above the hard
            maximum (200) are clamped silently. Set explicitly only when the
            default is too narrow for the investigation — the cap protects the
            LLM context window from runaway queries.
          format: int32
      description: >-
        Request DTO for the agent's KQL execution tool. Trimmed for LLM
        consumption — the

        agent supplies a query string the schema-aware sub-agent has already
        generated, and we

        run it under the workspace's Log Analytics context.
    ApiResponseOfAgentToolKqlQueryResult:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AgentToolKqlQueryResult'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    ApiProblemDetails:
      type: object
      properties:
        type:
          type:
            - 'null'
            - string
        title:
          type:
            - 'null'
            - string
        status:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
            - 'null'
            - integer
            - string
          format: int32
        detail:
          type:
            - 'null'
            - string
        instance:
          type:
            - 'null'
            - string
        code:
          type:
            - 'null'
            - string
        requestId:
          type:
            - 'null'
            - string
        timestamp:
          type:
            - 'null'
            - string
        target:
          type:
            - 'null'
            - string
        errors:
          type:
            - 'null'
            - object
          additionalProperties:
            type: array
            items:
              type: string
      description: >-
        API extension of ProblemDetails that surfaces the stable error code,

        trace identifier, timestamp, optional target, and optional field-keyed
        validation

        error map alongside the RFC 7807 members.
    AgentToolKqlQueryResult:
      type: object
      properties:
        success:
          type: boolean
          description: >-
            True when the query ran. False for KQL syntax errors, schema
            mismatches, upstream Log Analytics failures, or XDR-only workspaces
            — the failure reason is in `summary`.
        summary:
          type:
            - 'null'
            - string
          description: >-
            Compact human-readable digest: 'Query returned N rows.' or 'Query
            returned X rows; showing first N (truncated).' or a one-line failure
            reason.
        row_count:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
            - integer
            - string
          description: >-
            Number of rows actually returned (after server-side truncation).
            When `truncated` is true, this is less than the total rows the query
            matched.
          format: int32
        truncated:
          type: boolean
          description: >-
            True when the query produced more rows than were returned (hit the
            row cap). The agent should narrow the query (tighter time range,
            more selective filters, project fewer columns) rather than attempt
            pagination — these tools have no pagination contract. Omitted when
            false.
        columns:
          type:
            - 'null'
            - array
          items:
            type: string
          description: >-
            Column names in order. Index into each row in `rows` using the
            position of the column name here. Columns whose values were
            null/empty across every projected row are auto-pruned.
        rows:
          type:
            - 'null'
            - array
          items:
            type: array
            items:
              type: string
          description: >-
            Result rows as parallel arrays aligned to `columns`.
            Position-aligned: rows[r][c] is the value of columns[c] for row r.
            Values are stringified — booleans become 'true'/'false',
            objects/arrays become compact JSON, oversized cells are truncated
            with a `…(N more)` suffix.
      description: >-
        Result of an agent KQL execution tool call. Returns true-columnar rows
        (parallel arrays

        indexed against the List<string> AgentToolKqlQueryResult.Columns
        header) — far more token-efficient than a

        per-row dictionary because column names are written exactly once.
    ResponseMeta:
      type: object
      properties:
        requestId:
          type:
            - 'null'
            - string
        timestamp:
          type:
            - 'null'
            - string

````