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

# Query artifact metadata

> Executes one bounded, read-only ArtifactQuery statement over indexed artifact metadata for repository-level analytics: language and file-type mix, lines, cognitive complexity, largest files, public API surface, relationship counts. Statements must end with LIMIT. Invalid statements are not executed and return repairable diagnostics — fix the statement per the hint (see `get_artifact_query_schema`) and retry.



## OpenAPI

````yaml /openapi-tool-api-v3.json post /api/tools/query_artifact_metadata
openapi: 3.1.1
info:
  title: CodeAlive Tool API
  description: >-
    Tool-only OpenAPI 3.1 contract for MCP and agent integrations. Every
    operation is read-only and returns a Tool API envelope.
  contact:
    name: CodeAlive Team
    url: https://codealive.ai
    email: support@codealive.ai
  license:
    name: Terms of Service
    url: https://app.codealive.ai/terms
  version: 3.0.0
servers:
  - url: https://app.codealive.ai
security:
  - ApiKeyScheme: []
tags:
  - name: ToolApi
    description: CodeAlive Tool API v3
paths:
  /api/tools/query_artifact_metadata:
    post:
      tags:
        - ToolApi
      summary: Query artifact metadata
      description: >-
        Executes one bounded, read-only ArtifactQuery statement over indexed
        artifact metadata for repository-level analytics: language and file-type
        mix, lines, cognitive complexity, largest files, public API surface,
        relationship counts. Statements must end with LIMIT. Invalid statements
        are not executed and return repairable diagnostics — fix the statement
        per the hint (see `get_artifact_query_schema`) and retry.
      operationId: ToolApiQueryArtifactMetadata
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArtifactMetadataQueryToolRequest'
            example:
              statement: SELECT path, language FROM files LIMIT 20
              data_sources:
                - CodeAlive-AI/agent-framework
          text/json:
            schema:
              $ref: '#/components/schemas/ArtifactMetadataQueryToolRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/ArtifactMetadataQueryToolRequest'
      responses:
        '200':
          description: >-
            Success envelope. obj is the execution result: rawStatement,
            resultShape, columns, rows[] (column-keyed dictionaries),
            returnedRows, truncated, limit, dataSourceIds; rendered is the
            JSON-serialized form of obj. Repairable failures (missing or invalid
            arguments, ambiguous or unknown data sources) also return HTTP 200
            with obj.error = { code, message, retry, try } and a rendered
            <tool_error> block; repair the arguments and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolApiEnvelope'
              example:
                obj:
                  rawStatement: >-
                    SELECT count() AS count, language FROM files GROUP BY
                    language LIMIT 20
                  version: V1
                  resultShape: GroupedAggregate
                  columns:
                    - count
                    - language
                  rows:
                    - count: 214
                      language: python
                    - count: 32
                      language: markdown
                  returnedRows: 2
                  truncated: false
                  limit: 20
                  dataSourceIds:
                    - 665f1c2ab3e77d0c9a1b4d21
                rendered: >-
                  {"rawStatement":"SELECT count() AS count, language FROM files
                  GROUP BY language LIMIT
                  20","columns":["count","language"],"rows":[{"count":214,"language":"python"},{"count":32,"language":"markdown"}],"returnedRows":2,"limit":20}
            text/json:
              schema:
                $ref: '#/components/schemas/ToolApiEnvelope'
        '400':
          description: >-
            Bad request, including malformed JSON, unknown output_format, or
            invalid transport-level input.
        '401':
          description: Authentication failed or API key is missing.
        '403':
          description: >-
            The caller is not authorized for the requested data source or plan
            feature.
        '429':
          description: Rate limit, quota, or plan limit exceeded.
        '500':
          description: Unexpected server failure.
components:
  schemas:
    ArtifactMetadataQueryToolRequest:
      required:
        - statement
      type: object
      properties:
        output_format:
          enum:
            - json
            - agentic
          type:
            - 'null'
            - string
          description: >-
            Optional success projection. Omit to return both obj and rendered;
            use json for obj only; use agentic for rendered text only.
            Repairable errors always return both obj.error and rendered.
        statement:
          type:
            - 'null'
            - string
          description: >-
            One read-only ArtifactQuery statement. Use get_artifact_query_schema
            for supported entities, fields, and examples.
        data_sources:
          type:
            - 'null'
            - array
          items:
            type: string
          description: >-
            Repository or workspace names returned by get_data_sources. Omit
            only when the API key has a single unambiguous scope.
      additionalProperties: false
    ToolApiEnvelope:
      type: object
      properties:
        obj:
          description: >-
            Arbitrary JSON result for the tool. Present for omitted/json success
            projections and every repairable error.
        rendered:
          type:
            - 'null'
            - string
          description: >-
            Agent-facing result text. Present for omitted/agentic success
            projections and every repairable error.
      additionalProperties: false
  securitySchemes:
    ApiKeyScheme:
      type: http
      description: >-
        API Key authentication using Bearer token. Example: "Authorization:
        Bearer {apiKey}"
      scheme: bearer
      bearerFormat: API Key

````