---
updatedAt: 2026-05-20T03:31:39.000Z
agentTools:
  siteIndex: https://docs.jfrog.com/llms.txt
  projectIndex: https://docs.jfrog.com/artifactory/llms.txt
---

# Artifactory Query Language (AQL)

Flexible and high performance search using Artifactory Query Language. The request body is limited to 6,000 characters by default. For query size, result set limits, and syntax, see[AQL documentation](/artifactory/docs/artifactory-query-language).**Since:** 3.5.0**Security:** Requires an authenticated user. Certain domains/queries may require Admin access.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "JFrog Artifactory Searches API",
    "description": "REST API for searching artifacts, builds, and other items in JFrog Artifactory using various search methods including AQL, GAVC, property search, checksum search, and more.\n\n> **Important Note on Search Result Limits**\n>\n> All searches return limited results for internal and anonymous users (same limits as in the user interface).\n> To modify the default limit results, edit the `artifactory.system.properties` file with:\n> - `artifactory.search.limitAnonymousUsersOnly=false` (default is `true`)\n> - `artifactory.search.userQueryLimit` (default is `1000`)\n>\n> This applies to the following search APIs: Artifact Search, Archive Entries Search, GAVC Search, Property Search, Checksum Search (limited by UI max results),\n> Artifacts Not Downloaded Since, Artifacts With Date in Date Range, Artifacts Created in Date Range\n",
    "version": "1.0.0",
    "contact": {
      "name": "JFrog Support"
    }
  },
  "servers": [
    {
      "url": "https://{jfrog_url}/artifactory/api",
      "description": "JFrog Platform",
      "variables": {
        "jfrog_url": {
          "default": "myserver.jfrog.io",
          "description": "Your JFrog Platform hostname (e.g., mycompany.jfrog.io)"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Searches",
      "description": "Search operations for artifacts and builds"
    }
  ],
  "paths": {
    "/search/aql": {
      "post": {
        "tags": [
          "Searches"
        ],
        "summary": "Artifactory Query Language (AQL)",
        "operationId": "searchAql",
        "description": "Flexible and high performance search using Artifactory Query Language. The request body is limited to 6,000 characters by default. For query size, result set limits, and syntax, see[AQL documentation](/artifactory/docs/artifactory-query-language).**Since:** 3.5.0**Security:** Requires an authenticated user. Certain domains/queries may require Admin access.",
        "requestBody": {
          "required": true,
          "description": "AQL query string. Maximum length is 6,000 characters by default (`artifactory.aql.search.query.size.limit`). See AQL documentation for syntax reference.",
          "content": {
            "text/plain": {
              "schema": {
                "type": "string",
                "description": "AQL query string"
              },
              "examples": {
                "simpleItemSearch": {
                  "summary": "Search items in a repository",
                  "value": "items.find(\n  {\n    \"repo\":{\"$eq\":\"libs-release-local\"}\n  }\n)\n"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns matching items with a `results` array and `range` metadata indicating pagination bounds.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "range": {
                      "$ref": "#/components/schemas/AqlRange"
                    }
                  }
                },
                "examples": {
                  "aqlItemSearch": {
                    "summary": "Search items in a repository",
                    "value": {
                      "results": [
                        {
                          "repo": "libs-release-local",
                          "path": "org/jfrog/artifactory",
                          "name": "artifactory.war",
                          "type": "item type",
                          "size": "75500000",
                          "created": "2015-01-01T10:10:10",
                          "created_by": "Jfrog",
                          "modified": "2015-01-01T10:10:10",
                          "modified_by": "Jfrog",
                          "updated": "2015-01-01T10:10:10"
                        }
                      ],
                      "range": {
                        "start_pos": 0,
                        "end_pos": 1,
                        "total": 1,
                        "limit": 5,
                        "notification": "AQL query reached the search hard limit, results are trimmed."
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "security": [
    {
      "BasicAuth": []
    },
    {
      "ApiKeyAuth": []
    },
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BasicAuth": {
        "type": "http",
        "scheme": "basic",
        "description": "Username and password or username and API key."
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-JFrog-Art-Api",
        "description": "JFrog API key passed in the `X-JFrog-Art-Api` header."
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Access token obtained from JFrog Platform."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request is invalid. Check the error message for details.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "errors": [
                {
                  "status": 400,
                  "message": "Missing required parameters or invalid query."
                }
              ]
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Authentication credentials are missing or invalid.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "errors": [
                {
                  "status": 401,
                  "message": "Bad credentials"
                }
              ]
            }
          }
        }
      },
      "Forbidden": {
        "description": "The authenticated user does not have the required permissions.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "errors": [
                {
                  "status": 403,
                  "message": "User is not an admin"
                }
              ]
            }
          }
        }
      },
      "InternalServerError": {
        "description": "An unexpected server error occurred. If this persists, contact [JFrog Support](https://jfrog.com/help).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "errors": [
                {
                  "status": 500,
                  "message": "An unexpected error occurred"
                }
              ]
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "description": "Standard JFrog Platform error response envelope.",
        "required": [
          "errors"
        ],
        "properties": {
          "errors": {
            "type": "array",
            "description": "One or more error details.",
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            }
          }
        },
        "example": {
          "errors": [
            {
              "status": 400,
              "message": "Invalid request"
            }
          ]
        }
      },
      "ErrorDetail": {
        "type": "object",
        "required": [
          "message"
        ],
        "properties": {
          "status": {
            "type": "integer",
            "description": "HTTP status code.",
            "example": 400
          },
          "message": {
            "type": "string",
            "description": "Human-readable error description.",
            "minLength": 1,
            "example": "Invalid request"
          }
        }
      },
      "AqlRange": {
        "type": "object",
        "description": "Pagination/limit metadata returned by AQL queries.",
        "properties": {
          "start_pos": {
            "type": "integer"
          },
          "end_pos": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "notification": {
            "type": "string"
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false
  }
}
```