Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Kognitos Analytics API
description: REST API for Kognitos platform — PAT-eligible endpoints
version: 1.0.0
contact:
name: Kognitos
url: https://kognitos.com
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://app.us-1.kognitos.com
security:
- BearerAuth: []
tags:
- name: Analytics
description: Query dashboards, automation estimates, insights, and metrics.
paths:
/api/v1/organizations/{organization_id}/workspaces/{workspace_id}/dashboards:configureAutomationEstimates:
post:
summary: Configure Automation Estimates
operationId: ConfigureAutomationEstimates
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/dashboardsConfigureAutomationEstimatesResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
- name: workspace_id
in: path
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigureAutomationEstimatesBody'
required: true
tags:
- Analytics
/api/v1/organizations/{organization_id}/dashboards:queryInsights:
get:
summary: Query Insights
operationId: QueryInsights
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/dashboardsQueryInsightsResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
- name: filter.workspace_ids
description: 'Optional list of workspace IDs to filter insights.
Format: organizations/{organization}/workspaces/{workspace}
If empty, insights for all workspaces are returned.'
in: query
required: false
explode: true
schema:
type: array
items:
type: string
- name: filter.automation_ids
description: 'Optional list of automation IDs to filter insights.
Format: organizations/{organization}/workspaces/{workspace}/automations/{automation}
If empty, insights for all automations are returned.'
in: query
required: false
explode: true
schema:
type: array
items:
type: string
- name: filter.time_window.start_time
description: The start time of the window (inclusive).
in: query
required: true
schema:
type: string
format: date-time
- name: filter.time_window.end_time
description: The end time of the window (inclusive).
in: query
required: true
schema:
type: string
format: date-time
- name: filter.time_window.time_zone
description: 'The timezone for interpreting the time window.
Format: IANA timezone identifier (e.g., "America/New_York", "Europe/London").
Defaults to "UTC" if not specified.'
in: query
required: false
schema:
type: string
tags:
- Analytics
/api/v1/organizations/{organization_id}/dashboards:queryAutomationEstimates:
get:
summary: Query Automation Estimates
operationId: QueryAutomationEstimates
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/dashboardsQueryAutomationEstimatesResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
tags:
- Analytics
/api/v1/organizations/{organization_id}/metrics:query:
get:
summary: Query Metrics
description: 'This RPC retrieves time-series metric data for a specific organization,
supporting multiple metrics in a single request. Results can be filtered,
grouped, and sorted by tag dimensions.
The response contains one result per requested metric. Each result includes
multiple time series (one per unique group_by combination), with each series
containing chronologically ordered data points showing the aggregated metric
value over time.
Use the filter parameter (AIP-160 syntax) to restrict data to specific
tag values, and group_by to break down results by tag dimensions. The
order_by and page_size parameters enable sorting and limiting results
(useful for "top N" queries). The interval and aggregation parameters
control how data is aggregated. If not specified, the server will determine
appropriate defaults based on the time range.
Example use cases:
- Dashboard view: metrics=["runs", "pages"], group_by=["status"]
- Top 10 workspaces: metrics=["runs"], group_by=["workspace_id"],
order_by="value desc", page_size=10
- Success rate: metrics=["runs"], filter=''status = "success"''
- Multi-metric comparison: metrics=["files", "automations"],
group_by=["workspace_id"]'
operationId: QueryMetrics
responses:
'200':
description: A successful response.
content:
application/json:
schema:
$ref: '#/components/schemas/v1QueryMetricsResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/rpcStatus'
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
- name: metrics
description: 'The names of the metrics to query.
Identifies which metric types to retrieve data for in a single request.
All metrics will use the same filter, group_by, time range, interval,
and aggregation settings.
Examples: ["runs"], ["runs", "pages"], ["files", "automations"]'
in: query
required: true
explode: true
schema:
type: array
items:
type: string
- name: filter
description: 'Filter expression to apply before aggregation.
Reduces the dataset to only records matching the filter criteria.
Uses the AIP-160 filtering syntax for flexible query expressions.
An empty string means no filtering (all records included).
Supported operators: =, !=, AND, OR, NOT, IN
Examples:
- ''status = "success"''
- ''status = "success" AND workspace_id = "ws_123"''
- ''status IN ["success", "pending"]''
- ''workspace_id = "ws_123" OR workspace_id = "ws_456"''
See https://google.aip.dev/160 for full syntax specification.'
in: query
required: false
schema:
type: string
- name: group_by
description: 'Tag dimensions to group results by.
Each unique combination of these tag values becomes a separate time series.
An empty list means no grouping (single aggregated series).
Examples: ["status"], ["workspace_id", "status"]'
in: query
required: false
explode: true
schema:
type: array
items:
type: string
- name: start_time
description: 'Start time for the query range (inclusive).
Data points with timestamps on or after this time will be included.'
in: query
required: true
schema:
type: string
format: date-time
- name: end_time
description: 'End time for the query range (exclusive).
Data points with timestamps before this time will be included.'
in: query
required: true
schema:
type: string
format: date-time
- name: interval
description: "Requested time interval for aggregation.\n\nSpecifies the desired granularity for data points. The server may\nadjust this based on the time range or data availability.\n\nIf unspecified, the server will determine an appropriate interval.\n\n - METRIC_INTERVAL_UNSPECIFIED: Unspecified interval. Server will determine appropriate interval.\n - METRIC_INTERVAL_HOUR: Hourly aggregation.\n - METRIC_INTERVAL_DAY: Daily aggregation.\n - METRIC_INTERVAL_WEEK: Weekly aggregation.\n - METRIC_INTERVAL_MONTH: Monthly aggregation."
in: query
required: false
schema:
type: string
enum:
- METRIC_INTERVAL_UNSPECIFIED
- METRIC_INTERVAL_HOUR
- METRIC_INTERVAL_DAY
- METRIC_INTERVAL_WEEK
- METRIC_INTERVAL_MONTH
default: METRIC_INTERVAL_UNSPECIFIED
- name: aggregation
description: "Aggregation function to apply to metric values.\n\nSpecifies how values should be combined within each interval.\n\nIf unspecified, defaults to COUNT.\n\n - AGGREGATION_FUNCTION_UNSPECIFIED: Unspecified aggregation. Defaults to COUNT.\n - AGGREGATION_FUNCTION_COUNT: Count of occurrences.\n - AGGREGATION_FUNCTION_SUM: Sum of values.\n - AGGREGATION_FUNCTION_AVG: Average of values.\n - AGGREGATION_FUNCTION_MIN: Minimum value.\n - AGGREGATION_FUNCTION_MAX: Maximum value."
in: query
required: false
schema:
type: string
enum:
- AGGREGATION_FUNCTION_UNSPECIFIED
- AGGREGATION_FUNCTION_COUNT
- AGGREGATION_FUNCTION_SUM
- AGGREGATION_FUNCTION_AVG
- AGGREGATION_FUNCTION_MIN
- AGGREGATION_FUNCTION_MAX
default: AGGREGATION_FUNCTION_UNSPECIFIED
- name: order_by
description: 'Ordering for series results within each metric.
Uses AIP-132 syntax: "field_name [asc|desc]"
Multiple orderings can be comma-separated.
Supported fields:
- Tag names from group_by (e.g., "workspace_id asc", "status desc")
- "value" for sorting by aggregated metric value (uses last data point)
Examples:
- "value desc" - Highest values first (e.g., top workspaces)
- "workspace_id asc" - Alphabetical by workspace ID
- "value desc, workspace_id asc" - By value descending, then workspace ascending
If unspecified, series are returned in arbitrary order.
See https://google.aip.dev/132 for full syntax specification.'
in: query
required: false
schema:
type: string
- name: page_size
description: 'Maximum number of series to return per metric.
Limits the number of time series in each metric''s results.
Useful with order_by for "top N" queries.
If unspecified or zero, all matching series are returned.
If page_size is larger than the number of matching series, all series
are returned.
Example: order_by="value desc", page_size=10 returns top 10 series.'
in: query
required: false
schema:
type: integer
format: int32
- name: page_token
description: 'Pagination token for retrieving the next page of series.
When a response contains more series than page_size, the next_page_token
from the response can be passed here to retrieve the next page.
If empty, returns the first page of results.
See https://google.aip.dev/158 for pagination specification.'
in: query
required: false
schema:
type: string
tags:
- Analytics
components:
schemas:
v1AggregationFunction:
type: string
enum:
- AGGREGATION_FUNCTION_UNSPECIFIED
- AGGREGATION_FUNCTION_COUNT
- AGGREGATION_FUNCTION_SUM
- AGGREGATION_FUNCTION_AVG
- AGGREGATION_FUNCTION_MIN
- AGGREGATION_FUNCTION_MAX
default: AGGREGATION_FUNCTION_UNSPECIFIED
description: "Aggregation function for metric values.\n\nSpecifies how metric values should be aggregated within each interval.\n\n - AGGREGATION_FUNCTION_UNSPECIFIED: Unspecified aggregation. Defaults to COUNT.\n - AGGREGATION_FUNCTION_COUNT: Count of occurrences.\n - AGGREGATION_FUNCTION_SUM: Sum of values.\n - AGGREGATION_FUNCTION_AVG: Average of values.\n - AGGREGATION_FUNCTION_MIN: Minimum value.\n - AGGREGATION_FUNCTION_MAX: Maximum value."
dashboardsAutomationRunInsightList:
type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/dashboardsAutomationRunInsight'
description: List of run insights per automation.
readOnly: true
description: AutomationRunInsightList contains run insights for automations within a workspace.
ConfigureAutomationEstimatesBody:
type: object
properties:
automation_estimates:
type: array
items:
$ref: '#/components/schemas/dashboardsAutomationEstimate'
description: The list of automation estimates to configure.
description: 'Request message for ConfigureAutomationEstimates method.
Configures the estimated cost and time savings for automations within a workspace.'
required:
- automation_estimates
dashboardsAutomationEstimate:
type: object
properties:
automation_id:
type: string
title: 'The automation ID this estimate applies to.
Format: organizations/{organization}/workspaces/{workspace}/automations/{automation}'
cost_usd:
type: string
description: The estimated cost saved per run in USD.
time_saved_secs:
type: integer
format: int32
description: The estimated time saved per run in seconds.
description: AutomationEstimate represents the estimated value metrics for an automation.
required:
- automation_id
- cost_usd
- time_saved_secs
dashboardsCumulativeRunInsightList:
type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/dashboardsCumulativeRunInsight'
description: List of run insights per time period.
readOnly: true
description: CumulativeRunInsightList contains run insights grouped per time period within a workspace.
dashboardsRunsAwaitingGuidanceByPeriod:
type: object
properties:
window_label:
type: string
description: The display label of the time period (e.g., "January 2026", "December 2025").
readOnly: true
runs_awaiting_guidance:
type: string
format: int64
description: Number of runs created in this period that are awaiting guidance.
readOnly: true
description: RunsAwaitingGuidanceByPeriod contains runs awaiting guidance for a specific time period.
protobufAny:
type: object
properties:
'@type':
type: string
additionalProperties: {}
v1QueryMetricsResponse:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/v1MetricResult'
description: 'Results for each requested metric.
Ordered in the same sequence as the metrics field in the request.
Each result contains the time series data for one metric.'
readOnly: true
next_page_token:
type: string
description: 'Token for retrieving the next page of results.
If non-empty, there are more results available. Pass this value as
page_token in the next request to retrieve the next page.
If empty, there are no more results (this is the last page).
When paginating, all metrics will include their next page of series.
See https://google.aip.dev/158 for pagination specification.'
readOnly: true
description: 'Response message for the QueryMetrics RPC.
Contains results for each requested metric, with time series data
and metadata about the query execution.'
required:
- results
dashboardsCumulativeCompletionInsight:
type: object
properties:
window_label:
type: string
description: The display label of the time period (e.g., "Week 1", "January 2025").
readOnly: true
auto_completed_count:
type: string
format: int64
description: Number of runs that completed automatically without manual intervention.
readOnly: true
manually_resolved_count:
type: string
format: int64
description: Number of runs that required manual resolution.
readOnly: true
description: CumulativeCompletionInsight contains completion metrics for a specific time period.
dashboardsRunInsight:
type: object
properties:
total_runs_count:
type: string
format: int64
description: Total number of runs across all automations and workspaces.
readOnly: true
insights_per_automation_per_workspace:
type: object
additionalProperties:
$ref: '#/components/schemas/dashboardsAutomationRunInsightList'
title: 'Run insights grouped per automation per workspace.
Key: workspace_id (format: organizations/{org}/workspaces/{workspace})'
readOnly: true
insights_per_period_per_workspace:
type: object
additionalProperties:
$ref: '#/components/schemas/dashboardsCumulativeRunInsightList'
title: 'Run insights grouped per time period per workspace.
Key: workspace_id (format: organizations/{org}/workspaces/{workspace})'
readOnly: true
trend:
$ref: '#/components/schemas/dashboardsTrend'
description: RunInsight contains aggregated runCount metrics.
dashboardsCompletionInsight:
type: object
properties:
total_percent_completions:
type: number
format: double
description: Overall completion percentage across all runs.
readOnly: true
completions_per_period:
type: array
items:
$ref: '#/components/schemas/dashboardsCumulativeCompletionInsight'
description: Completion insights grouped per time period.
readOnly: true
trend:
$ref: '#/components/schemas/dashboardsTrend'
stp:
type: number
format: double
description: Straight-through processing rate.
readOnly: true
description: CompletionInsight contains completion rate metrics.
v1MetricInterval:
type: string
enum:
- METRIC_INTERVAL_UNSPECIFIED
- METRIC_INTERVAL_HOUR
- METRIC_INTERVAL_DAY
- METRIC_INTERVAL_WEEK
- METRIC_INTERVAL_MONTH
default: METRIC_INTERVAL_UNSPECIFIED
description: "Time interval for metric aggregation.\n\nSpecifies the granularity at which metric data points are aggregated.\nThe server may adjust the requested interval based on the time range\nor data availability.\n\n - METRIC_INTERVAL_UNSPECIFIED: Unspecified interval. Server will determine appropriate interval.\n - METRIC_INTERVAL_HOUR: Hourly aggregation.\n - METRIC_INTERVAL_DAY: Daily aggregation.\n - METRIC_INTERVAL_WEEK: Weekly aggregation.\n - METRIC_INTERVAL_MONTH: Monthly aggregation."
v1MetricDataPoint:
type: object
properties:
start_time:
type: string
format: date-time
description: 'The start time for this data point''s interval.
Represents the start of the interval for which the value is aggregated.'
readOnly: true
value:
type: number
format: double
description: 'The aggregated metric value for this interval.
Result of applying the aggregation function to all matching records
within this interval for this series'' tag combination.'
readOnly: true
window_label:
type: string
description: 'Human-readable label for the time window.
Provides a formatted display name for the interval, formatted according
to the interval granularity and the user''s locale preferences.
Examples:
- HOUR: "Jan 15, 2025 10:00 AM", "2025-01-15 10:00"
- DAY: "January 15, 2025", "2025-01-15"
- WEEK: "Week of Jan 15, 2025", "2025-W03"
- MONTH: "January 2025", "2025-01"'
readOnly: true
description: 'A single data point in a metric time series.
Represents an aggregated metric value at a specific point in time.'
required:
- start_time
- value
- window_label
dashboardsQueryInsightsResponse:
type: object
properties:
value_insight:
$ref: '#/components/schemas/dashboardsValueInsight'
run_insight:
$ref: '#/components/schemas/dashboardsRunInsight'
completion_insight:
$ref: '#/components/schemas/dashboardsCompletionInsight'
awaiting_guidance_insight:
$ref: '#/components/schemas/dashboardsAwaitingGuidanceInsight'
description: 'Response message for QueryInsights method.
Contains aggregated analytics insights across value, runs, and completions.'
dashboardsConfigureAutomationEstimatesResponse:
type: object
properties:
automation_estimates:
type: array
items:
$ref: '#/components/schemas/dashboardsAutomationEstimate'
description: The list of configured automation estimates.
readOnly: true
description: 'Response message for ConfigureAutomationEstimates method.
Returns the configured automation estimates for the workspace.'
rpcStatus:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
$ref: '#/components/schemas/protobufAny'
dashboardsCumulativeRunInsight:
type: object
properties:
window_label:
type: string
description: The display label of the time period (e.g., "Week 1", "January 2025").
readOnly: true
runs_count:
type: string
format: int64
description: Number of runs during this period.
readOnly: true
description: CumulativeRunInsight contains run count metrics for a specific time period.
dashboardsValueInsight:
type: object
properties:
total_money_saved_usd:
type: string
description: Total money saved across all automations and workspaces in USD.
readOnly: true
total_time_saved_secs:
type: string
format: int64
description: Total time saved across all automations and workspaces in seconds.
readOnly: true
insights_per_automation_per_workspace:
type: object
additionalProperties:
$ref: '#/components/schemas/dashboardsAutomationValueInsightList'
title: 'Value insights grouped per automation per workspace.
Key: workspace_id (format: organizations/{org}/workspaces/{workspace})'
readOnly: true
insights_per_period_per_workspace:
type: object
additionalProperties:
$ref: '#/components/schemas/dashboardsCumulativeValueInsightList'
title: 'Value insights grouped per time period per workspace.
Key: workspace_id (format: organizations/{org}/workspaces/{workspace})'
readOnly: true
description: ValueInsight contains aggregated value metrics (cost and time savings).
dashboardsAutomationValueInsight:
type: object
properties:
automation_id:
type: string
title: 'The automation ID.
Format: organizations/{organization}/workspaces/{workspace}/automations/{automation}'
readOnly: true
display_name:
type: string
description: The display name of the automation.
readOnly: true
time_saved_secs:
type: string
format: int64
description: Time saved by this automation in seconds.
readOnly: true
money_saved_usd:
type: string
description: Money saved by this automation in USD.
readOnly: true
description: AutomationValueInsight contains value metrics for a specific automation.
dashboardsTrend:
type: object
properties:
percent_change:
type: number
format: double
description: 'The percentage change compared to the previous time window.
Positive values indicate increase, negative values indicate decrease.'
readOnly: true
comparison_window:
type: string
description: The label of the time window being compared against (e.g., "Last Week", "Previous Month").
readOnly: true
description: Trend represents a percentage change compared to a previous time window.
dashboardsQueryAutomationEstimatesResponse:
type: object
properties:
workspace_estimates:
type: object
additionalProperties:
$ref: '#/components/schemas/dashboardsAutomationEstimateList'
title: 'Automation estimates grouped per workspace.
Key: workspace_id (format: organizations/{org}/workspaces/{workspace})'
readOnly: true
description: 'Response message for QueryAutomationEstimates method.
Contains automation estimates grouped by workspace.'
dashboardsAutomationValueInsightList:
type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/dashboardsAutomationValueInsight'
description: List of value insights per automation.
readOnly: true
description: AutomationValueInsightList contains value insights for automations within a workspace.
v1MetricResult:
type: object
properties:
metric:
type: string
description: 'The name of this metric.
Echoes back the metric name from the request.'
readOnly: true
interval:
$ref: '#/components/schemas/v1MetricInterval'
aggregation:
$ref: '#/components/schemas/v1AggregationFunction'
series:
type: array
items:
$ref: '#/components/schemas/v1MetricSeries'
description: 'Multiple time series, one per unique group_by combination.
If group_by is empty, there will be exactly one series with empty tags.
If group_by has values, there will be one series per unique combination
found in the data.
Series are ordered according to the order_by parameter in the request.
If page_size was specified, results are paginated across all metrics.
The list may be empty if no data exists for the requested time range.'
readOnly: true
description: 'Result for a single metric query.
Contains the time series data and metadata for one metric.'
required:
- metric
- interval
- aggregation
- series
dashboardsAwaitingGuidanceInsight:
type: object
properties:
total_runs_awaiting_guidance:
type: string
format: int64
description: Total number of runs awaiting guidance.
readOnly: true
runs_per_period:
type: array
items:
$ref: '#/components/schemas/dashboardsRunsAwaitingGuidanceByPeriod'
description: Runs awaiting guidance grouped per time period.
readOnly: true
description: AwaitingGuidanceInsight contains metrics for runs awaiting guidance.
dashboardsAutomationEstimateList:
type: object
properties:
estimates:
type: array
items:
$ref: '#/components/schemas/dashboardsAutomationEstimate'
description: List of automation estimates for a workspace.
readOnly: true
description: Wrapper for a list of automation estimates.
dashboardsCumulativeValueInsight:
type: object
properties:
window_label:
type: string
description: The display label of the time period (e.g., "Week 1", "January 2025").
readOnly: true
time_saved_secs:
type: string
format: int64
description: Time saved during this period in seconds.
readOnly: true
money_saved_usd:
type: string
description: Money saved during this period in USD.
readOnly: true
description: CumulativeValueInsight contains value metrics for a specific time period.
dashboardsCumulativeValueInsightList:
type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/dashboardsCumulativeValueInsight'
description: List of value insights per time period.
readOnly: true
description: CumulativeValueInsightList contains value insights grouped per time period within a workspace.
v1MetricSeries:
type: object
properties:
tags:
type: object
additionalProperties:
type: string
description: 'Tags identifying this series.
The unique combination of group_by tag values that define this series.
If group_by is empty, this will be an empty map.
Example: {"status": "success", "workspace_id": "ws_123"}'
readOnly: true
points:
type: array
items:
$ref: '#/components/schemas/v1MetricDataPoint'
description: 'Time series data points for this specific tag combination.
Chronologically ordered data points showing the metric value over time.'
readOnly: true
description: 'A single time series for a specific combination of tag values.
Each series represents one unique combination of the group_by dimensions,
containing data points over time for that specific combination.'
required:
- tags
- points
dashboardsAutomationRunInsight:
type: object
properties:
automation_id:
type: string
title: 'The automation ID.
Format: organizations/{organization}/workspaces/{workspace}/automations/{automation}'
readOnly: true
display_name:
type: string
description: The display name of the automation.
readOnly: true
runs_count:
type: string
format: int64
description: Number of runs for this automation.
readOnly: true
description: AutomationRunInsight contains run count metrics for a specific automation.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Personal Access Token.