Skip to main content
​

​
Summary

  • The Labs API is now a superset of the Astro API v1. It serves every v1 endpoint at the same path, and where Labs defines its own operation at the same method and path, it serves the Labs version.
  • Added load watermarks to the daily-usage response, so callers can tell a usage date that has finished loading from one that is still filling in.
  • Added hostProviderName to the FOCUS-format daily-usage response.

​
Added

  • Properties
    • completeThroughDate (string), dataAsOf (string, date-time): added to DailyUsagesPaginated, the response of GET /organizations/{organizationId}/billing/daily-usage (LabsListDailyUsage). completeThroughDate is the last usage date, in UTC, whose load has finished. dataAsOf is when the Organization’s most recent cost row was written, in UTC. Both values cover all of the Organization’s usage data regardless of the request’s filters, and the response omits both when the Organization has no cost data.
    • x_CompleteThroughDate, x_DataAsOf: added to FocusDailyUsagesPaginated, the FOCUS-format equivalent of the above.
    • hostProviderName (string, required): added to FocusDailyUsage. The cloud provider hosting the charged infrastructure, for example AWS.
​

​
Summary

  • Added bulk create/delete endpoints for organization notification channels.
  • Added cursor-based pagination to the daily-usage, deployment-usage, and workspace-usage endpoints, alongside the existing offset pagination.
  • Moved the per-deployment and per-workspace usage endpoints from under /billing to /usages — a breaking path change for existing callers.
  • Added computeType/workerQueueName to the daily-usage response, and billingCurrency/x_ComputeType/x_WorkerQueueName to its FOCUS-format variant, so cost rows from different worker queues at the same compute size are no longer indistinguishable.

​
Added

  • Endpoints
    • POST /organizations/{organizationId}/notification-channels (LabsCreateNotificationChannels): Create up to 30 notification channels for an organization in one atomic request. Not idempotent — a retry after an unacknowledged 2xx response creates the channels a second time. Returns a NotificationChannelsList.
    • DELETE /organizations/{organizationId}/notification-channels (LabsDeleteNotificationChannels): Delete up to 30 notification channels for an organization in one atomic request. Fails the whole batch if any channel is not found, is still used by an alert or a monitor, or the caller cannot delete it.
  • Schemas
    • NotificationChannel, NotificationChannelsList: a single notification channel and the list returned by the bulk create endpoint.
    • BulkCreateNotificationChannelsRequest, BulkDeleteNotificationChannelsRequest: request bodies for the bulk create/delete endpoints (at most 30 channels or IDs per request).
    • CreateNotificationChannelRequest: discriminated by type, with one variant per channel type — CreateSlackNotificationChannelRequest, CreateEmailNotificationChannelRequest, CreatePagerDutyNotificationChannelRequest, CreateOpsgenieNotificationChannelRequest, CreateDagTriggerNotificationChannelRequest.
    • SlackNotificationChannelDefinition, EmailNotificationChannelDefinition, PagerDutyNotificationChannelDefinition, OpsgenieNotificationChannelDefinition, DagTriggerNotificationChannelDefinition: the type-specific channel configuration (webhook URL, recipients, integration key, API key, or Dag trigger details).
  • Properties
    • pageSize, pageToken (query parameters), and nextPageToken, pageSize, previousPageToken (response fields, all required): added to the daily-usage, deployment-usage, and workspace-usage endpoints, enabling cursor-mode pagination (AIP-158) alongside the existing offset/limit mode.
    • computeType, workerQueueName (strings): added to DailyUsage. The compute instance type and worker queue a cost row is attributed to, if applicable.
    • billingCurrency (string, required), x_ComputeType, x_WorkerQueueName: added to FocusDailyUsage, the FOCUS-format equivalent of the above.

​
Changed

  • GET /organizations/{organizationId}/billing/aggregate/deployment-usage and .../workspace-usage moved to GET /organizations/{organizationId}/usages/aggregate/deployment-usage and .../workspace-usage. This is a breaking path change for existing callers; the daily-usage (cost) endpoint path is unchanged.
  • sorts on the daily-usage, deployment-usage, and workspace-usage endpoints is now a closed enum of <field>:asc/<field>:desc values instead of an unconstrained string.
  • limit’s minimum on these endpoints changed from 0 to 1.
  • Endpoint descriptions no longer reference the internal Sigma cost breakdown export system that backs this data.
​

​
Summary

  • Added bulk create/delete endpoints for organization allowed IP address ranges.
  • Added an endpoint to retrieve Organization audit logs for a time period.
  • Added three billing usage endpoints: daily usage, per-deployment usage, and per-workspace usage, synced from the org’s Sigma cost breakdown export.

​
Added

  • Endpoints
    • POST /organizations/{organizationId}/allowed-ip-address-ranges (LabsCreateAllowedIpAddressRanges): Bulk create up to 1,000 allowed IP address (CIDR) ranges for an organization in one atomic request. Not idempotent — a retry after an unacknowledged 2xx may return 409. Returns an AllowedIpAddressRangesList.
    • DELETE /organizations/{organizationId}/allowed-ip-address-ranges (LabsDeleteAllowedIpAddressRanges): Bulk delete up to 1,000 allowed IP address ranges for an organization in one atomic request. Unknown or duplicate IDs are accepted and ignored.
    • GET /organizations/{organizationId}/audit-logs (LabsGetOrganizationAuditLogs): Retrieve an organization’s audit logs for a time period, filtered with startDate and endDate. Returns a raw byte stream (application/octet-stream).
    • GET /organizations/{organizationId}/billing/daily-usage (LabsListDailyUsage): List daily deployment resource cost data. Filter by startDate/endDate (max 12 months), workspaceId, or deploymentId (up to 1,000 each), and choose the response shape with format (astronomer or focus — FOCUS format). Paginate with offset/limit and sort with sorts. Enterprise+ tier only.
    • GET /organizations/{organizationId}/billing/aggregate/deployment-usage (LabsListDeploymentUsage): List per-deployment task, Dag, and operator activity metrics, aggregated by day, week, or month (timeGrain). Filter by startDate/endDate (max 12 months), workspaceId, or deploymentId. Enterprise+ tier only.
    • GET /organizations/{organizationId}/billing/aggregate/workspace-usage (LabsListWorkspaceUsage): List per-workspace task, Dag, and operator activity metrics, aggregated by day, week, or month (timeGrain). Filter by startDate/endDate (max 12 months) or workspaceId. Enterprise+ tier only.
  • Schemas
    • AllowedIpAddressRange, AllowedIpAddressRangesList: represent a single allowed IP range and a paginated list of them.
    • BulkCreateAllowedIpAddressRangesRequest, BulkDeleteAllowedIpAddressRangesRequest: request bodies for the bulk create/delete endpoints.
    • DailyUsage, DailyUsageVariants, DailyUsagesPaginated: standard-format daily usage records and paginated response.
    • FocusDailyUsage, FocusDailyUsagesPaginated: FOCUS-format daily usage records and paginated response.
    • DeploymentUsage, DeploymentUsagesPaginated: per-deployment usage records and paginated response.
    • WorkspaceUsage, WorkspaceUsagesPaginated: per-workspace usage records and paginated response.
​

​
Summary

  • Added a LabsListAlerts endpoint to the Labs API. GET /organizations/{organizationId}/alerts lists alerts and their notification channels, with filtering by alert or deployment IDs.

​
Added

  • Endpoints
    • GET /organizations/{organizationId}/alerts (LabsListAlerts): List alerts, including their notification channels. Filter with alertIds or deploymentIds (up to 1,000 IDs each) and paginate with offset and limit (default 20, maximum 1,000). Returns an AlertsList.
​

​
Summary

  • Added bulk alert management to the Labs API. New create-alerts, update-alerts, and delete-alerts endpoints let clients manage up to 30, 30, and 20 alerts per request across six alert types: Dag success, Dag failure, Dag duration, Dag timeliness, task duration, and task failure.

​
Added

  • Endpoints
    • POST /organizations/{organizationId}/create-alerts (LabsCreateAlerts): Bulk create up to 30 alerts. Takes a CreateAlertsRequest and returns an AlertsList.
    • POST /organizations/{organizationId}/update-alerts (LabsUpdateAlerts): Bulk update up to 30 alerts. Takes an UpdateAlertsRequest and returns an AlertsList.
    • POST /organizations/{organizationId}/delete-alerts (LabsDeleteAlerts): Bulk delete up to 20 alerts. Takes a DeleteAlertsRequest. Returns 204 with no response body.
  • Schemas
    • Alert, AlertsList, AlertNotificationChannel, AlertRules, BasicSubjectProfile: Response shapes for an alert, a list of alerts, a notification channel, an alert’s rules, and the profile of the user or API token that created or updated an alert.
    • CreateAlertsRequest, UpdateAlertsRequest, DeleteAlertsRequest: Bulk request wrappers. CreateAlertsRequest and UpdateAlertsRequest each wrap a list of CreateAlertRequest or UpdateAlertRequest, a type-discriminated union over the six alert types. DeleteAlertsRequest wraps a list of alertIds.
    • Per-type request, properties, and rules schemas: each of the six alert types (DAG_SUCCESS, DAG_FAILURE, DAG_DURATION, DAG_TIMELINESS, TASK_DURATION, and TASK_FAILURE) gets its own create and update request, properties, and rules schemas, for example CreateDagDurationAlertRequest, CreateDagDurationAlertProperties, and CreateDagDurationAlertRules for Dag duration alerts. Each type’s properties schema holds its type-specific configuration, for example dagDurationSeconds for Dag duration alerts or dagDeadline and daysOfWeek for Dag timeliness alerts.
    • PatternMatch, PatternMatchRequest: Scope an alert to specific Dag or task IDs using an entityType (DAG_ID or TASK_ID) and operatorType (IS, IS_NOT, INCLUDES, or EXCLUDES).
​

​
Summary

  • Initial release of the Astro Labs API, an experimental surface for Labs features.
  • Adds Observability endpoints for AI-powered Dag-failure diagnosis: start a diagnosis run, poll its status, and stream its events over Server-Sent Events.
  • Adds a demonstration Example endpoint that shows how Labs minor-version pinning behaves through the X-Labs-API-Version header.

​
Added

  • Endpoints
    • POST /organizations/{organizationId}/observability/deployments/{deploymentId}/dag-failure-diagnosis/runs: Start an asynchronous Dag-failure diagnosis run.
    • GET /organizations/{organizationId}/observability/deployments/{deploymentId}/dag-failure-diagnosis/runs/{diagnosisRunId}/status: Get the status of a diagnosis run.
    • GET /organizations/{organizationId}/observability/deployments/{deploymentId}/dag-failure-diagnosis/runs/{diagnosisRunId}/events: Stream diagnosis events over Server-Sent Events, with reconnection through the lastEventId query parameter.
  • Schemas
    • DagFailureDiagnosisRun: A started diagnosis run. Includes runId, status, and createdAt.
    • DagFailureDiagnosisRunStatus: The current status of a diagnosis run. Includes runId, status, createdAt, and updatedAt.
    • StartDagFailureDiagnosisRequest: The request body for starting a run. Required: dagId, runId. Optional: taskId, tryNumbers, skipCacheRead.
    • Example: The demonstration response. Includes id, createdAt, and proofOfConcept.
    • Error: The error response shape. Includes message, statusCode, and requestId.