# Insights

## Execute analytics query

> Runs a custom analytics query and returns results in tabular format.\
> \
> \## Authorization\
> Requires \`Insights.Read\` scope.\
> \
> \## Rate Limiting\
> Limited to 60 requests per interval to protect analytics infrastructure.\
> \
> \## Query Language\
> Typically uses Kusto Query Language (KQL) syntax:\
> \`\`\`kql\
> Passes\
> \| where timestamp > ago(7d)\
> \| summarize count() by passType\
> \| order by count\_ desc\
> \`\`\`\
> \
> \## Parameters\
> Supports parameterized queries for security and reusability:\
> \`\`\`json\
> {\
>   "query": "Events | where Name == name | take 100",\
>   "parameters": { "name": "Pass:Installed" }\
> }\
> \`\`\`\
> \## Use Cases\
> \- Custom dashboards\
> \- Business intelligence reports\
> \- Data exports\
> \- Trend analysis\
> \
> \## Performance\
> \- Query timeout: Configurable per tenant\
> \- Result limits: May be enforced\
> \- Caching: Not automatic - implement client-side if needed

````json
{"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"Insights"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"QueryRequest":{"required":["query"],"type":"object","properties":{"query":{"type":"string"},"parameters":{"type":"object","additionalProperties":{"type":"string"}},"options":{"$ref":"#/components/schemas/QueryOptions"}},"additionalProperties":false},"QueryOptions":{"type":"object","additionalProperties":false},"QueryResponse":{"type":"object","properties":{"columns":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"array","items":{}}}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/insights/query":{"post":{"tags":["Insights"],"summary":"Execute analytics query","description":"Runs a custom analytics query and returns results in tabular format.\n\n## Authorization\nRequires `Insights.Read` scope.\n\n## Rate Limiting\nLimited to 60 requests per interval to protect analytics infrastructure.\n\n## Query Language\nTypically uses Kusto Query Language (KQL) syntax:\n```kql\nPasses\n| where timestamp > ago(7d)\n| summarize count() by passType\n| order by count_ desc\n```\n\n## Parameters\nSupports parameterized queries for security and reusability:\n```json\n{\n  \"query\": \"Events | where Name == name | take 100\",\n  \"parameters\": { \"name\": \"Pass:Installed\" }\n}\n```\n## Use Cases\n- Custom dashboards\n- Business intelligence reports\n- Data exports\n- Trend analysis\n\n## Performance\n- Query timeout: Configurable per tenant\n- Result limits: May be enforced\n- Caching: Not automatic - implement client-side if needed","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"The query text, parameters, and optional execution settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/QueryRequest"}}}},"responses":{"200":{"description":"Query executed successfully","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/QueryResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/QueryResponse"}}}},"400":{"description":"Invalid query syntax or parameters","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"401":{"description":"Not authorized","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"500":{"description":"Internal server error while executing query"}}}}}}
````