API reference

Members API

The root URL for the endpoints below is: /v1/org/members

Method	Endpoint	Description
GET	/	List members
POST	/invitations	Send an invitation
GET	/invitations	List invitations
DELETE	/invitations/:id	Revoke an invitation
PATCH	/:id	Update member role
DELETE	/:id	Remove a member

API tokens

The root URL for the endpoints below is: /v1/auth/tokens

Method	Endpoint	Description
POST	/	Create an API token
GET	/	List API tokens
DELETE	/:id	Delete an API token

Studio API

The root URL for the endpoints below is: /v1/studio

Method	Endpoint	Description
GET	/projects	List studio projects
POST	/projects	Create a project
GET	/projects/:id	Get project detail and deploys
DELETE	/projects/:id	Delete a project
POST	/deploys	Create a deploy
POST	/deploys/:id/upload-complete	Confirm artifact upload
GET	/deploys/:id	Get deploy status
GET	/deploys/:id/logs	Get deploy logs
GET	/deploys/:id/logs/stream	Stream deploy logs (SSE)

Server API

The root URL for the endpoints below is: /v1/server

Method	Endpoint	Description
GET	/projects	List server projects
POST	/projects	Create a project
GET	/projects/:id	Get project detail
DELETE	/projects/:id	Delete a project
PUT	/projects/:id/env	Set environment variables
GET	/projects/:id/env	Get environment variables
POST	/projects/:id/env/restart	Restart after env change
GET	/projects/:id/domains	List domains
POST	/projects/:id/domains	Add a custom domain
GET	/projects/:id/runtime-logs	Get runtime logs
POST	/projects/:id/redeploy	Trigger redeploy
POST	/projects/:id/always-on	Enable always-on
DELETE	/projects/:id/always-on	Disable always-on
POST	/deploys	Create a deploy
POST	/deploys/:id/upload-complete	Confirm artifact upload
GET	/deploys/:id	Get deploy status
GET	/deploys/:id/logs	Get deploy logs
POST	/deploys/:id/cancel	Cancel a queued or in-progress deploy
DELETE	/deploys/:id	Stop a running deploy

Gateway API

The root URL for the endpoints below is: /v1/gateway

Method	Endpoint	Description
GET	/projects	List gateway projects
GET	/projects/:id	Get project detail
PATCH	/projects/:id	Update project settings
DELETE	/projects/:id	Delete a project
POST	/projects/provision	Provision a new gateway project
GET	/projects/:id/keys	List API keys
POST	/projects/:id/keys	Create an API key
DELETE	/projects/:id/keys/:keyId	Revoke an API key
GET	/projects/:id/keys/:keyId/bindings	List key-level provider bindings
POST	/projects/:id/keys/:keyId/bindings	Add a key-level provider binding (BYOK)
DELETE	/projects/:id/keys/:keyId/bindings/:provider	Remove a key-level binding
GET	/projects/:id/bindings	List project-level provider bindings
POST	/projects/:id/bindings	Add a project-level provider binding (BYOK)
DELETE	/projects/:id/bindings/:provider	Remove a project-level binding
GET	/projects/:id/usage/has-activity	Check whether project has any requests
GET	/projects/:id/usage/activity	Get aggregated usage activity
GET	/projects/:id/usage/memory-activity	Get memory-token totals over a time range
GET	/projects/:id/usage/logs	Get request logs
GET	/projects/:id/usage/logs/facets	Get log filter facets
GET	/projects/:id/usage/logs/:requestId	Get specific request detail
GET	/projects/:id/memory/threads	List threads (dashboard)
POST	/projects/:id/memory/threads	Create a thread (dashboard)
GET	/projects/:id/memory/threads/:threadId	Get thread (dashboard)
PATCH	/projects/:id/memory/threads/:threadId	Update thread (dashboard)
DELETE	/projects/:id/memory/threads/:threadId	Delete thread (dashboard)
POST	/projects/:id/memory/threads/:threadId/clone	Clone thread (dashboard)
GET	/projects/:id/memory/threads/:threadId/messages	List messages (dashboard)
POST	/projects/:id/memory/threads/:threadId/messages	Save messages (dashboard)
DELETE	/projects/:id/memory/threads/:threadId/messages	Delete messages (dashboard)
GET	/projects/:id/memory/threads/:threadId/observations/history	Observation history (dashboard)
GET	/models	List available models

Feedback API

The Feedback API lists and analyzes feedback exported to Mastra Platform Observability. Because the API is unversioned, backwards compatibility isn't guaranteed. Rate limits, retention, and ingestion-to-query freshness aren't published contracts.

The endpoints share their query parameters, request bodies, and response types with the Mastra runtime feedback routes. See the feedback reference for the full contract, including list query parameters and FeedbackFilter.

Use the root URL for your environment's data-residency region:

Region	Root URL
United States	https://observability.mastra.ai/api/observability
European Union	https://observability.eu.mastra.ai/api/observability

Telemetry stays in its residency region. Querying the other region returns no records for the environment. See Observability co-location for the environment-to-region mapping.

Authentication and project scope

Every request requires a platform access token. Create one in Mastra Platform, or use the token written to .env during Platform setup.

Include X-Mastra-Project-Id to limit results to one project. If you omit it, the query covers feedback in every project available to the token's organization.

curl -sS "https://observability.mastra.ai/api/observability/feedback?page=0&perPage=20&feedbackType=rating" \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq

Use an organization-scoped Platform access token. Gateway inference keys such as mk_* keys aren't accepted. Queries remain constrained to the token's organization even when you supply a project ID.

Endpoints

Method	Endpoint	Description
GET	/feedback	List feedback records
POST	/feedback/aggregate	Return one aggregate value
POST	/feedback/breakdown	Group feedback by dimensions
POST	/feedback/timeseries	Bucket feedback by interval
POST	/feedback/percentiles	Return percentile series

The list endpoint takes every FeedbackFilter field as a query parameter with the same name, for example traceId, spanId, feedbackType, feedbackSource, environment, entityName, experimentId, or tags. Repeat a parameter for multiple values, such as feedbackType=rating&feedbackType=thumbs.

curl -sS "https://observability.mastra.ai/api/observability/feedback?traceId=trace-123&environment=production" \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq

Parameter	Description
page, perPage	Zero-indexed page and page size (1 to 100). Default 0 and 10.
field, direction	Sort by timestamp in ASC or DESC order. Default DESC.
mode=delta	Switch from paging to incremental delta polling.
after	Delta cursor from the previous delta response. Delta mode only.
limit	Maximum updates per delta poll (1 to 100). Delta mode only.

Responses contain a feedback array and page or delta metadata. See list query parameters in the feedback reference for the full parameter contract, including JSON-encoded object filters such as timestamp.

Analytics endpoints accept the same JSON request shapes and return types as the feedback reference. Analytics operate only on numeric feedback values.

curl -sS "https://observability.mastra.ai/api/observability/feedback/aggregate" \
  -X POST \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" \
  -H "Content-Type: application/json" \
  --data '{"feedbackType":"rating","feedbackSource":"user","aggregation":"avg"}' | jq

The API returns 401 for invalid credentials, 403 for organization authorization failures, and 400 for malformed query arguments or JSON bodies.

Hosted observability doesn't provide a feedback creation route. Export feedback from the application as described in Export feedback to Mastra Platform.

Metrics API

The Metrics API queries metrics exported to Mastra Platform Observability. Because the API is unversioned, backwards compatibility isn't guaranteed. Rate limits, retention, and ingestion-to-query freshness aren't published contracts.

The endpoints share their query parameters, request bodies, and response types with the Mastra runtime metric routes. See the metric queries reference for the full contract, including shared filters, analytics methods, and metric discovery.

Use the root URL for your environment's data-residency region:

Region	Root URL
United States	https://observability.mastra.ai/api/observability
European Union	https://observability.eu.mastra.ai/api/observability

Telemetry stays in its residency region. Querying the other region returns no records for the environment. See Observability co-location for the environment-to-region mapping.

Authentication and project scope

Every request requires a platform access token. Create one in Mastra Platform, or use the token written to .env during Platform setup.

Include X-Mastra-Project-Id to limit results to one project. If you omit it, the query covers metrics in every project available to the token's organization.

curl -sS "https://observability.mastra.ai/api/observability/discovery/metric-names?prefix=mastra_model_" \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq

Use an organization-scoped Platform access token. Gateway inference keys such as mk_* keys aren't accepted. Queries remain constrained to the token's organization even when you supply a project ID.

Endpoints

Method	Endpoint	Description
GET	/metrics	List raw metric records
POST	/metrics/aggregate	Return one aggregate value
POST	/metrics/breakdown	Group metrics by dimensions
POST	/metrics/timeseries	Bucket metrics by interval
POST	/metrics/percentiles	Return percentile series for one metric
GET	/discovery/metric-names	List metric names
GET	/discovery/metric-label-keys	List label keys for a metric
GET	/discovery/metric-label-values	List values for a metric label key

The list and discovery endpoints take their arguments as query parameters. See listMetrics(args) and metric discovery in the metric queries reference for the parameters each one accepts.

Analytics endpoints accept the same JSON request bodies and return types as the metric queries reference, including name, aggregation, filters, groupBy, interval, percentiles, comparePeriod, limit, orderDirection, and distinctColumn.

curl -sS "https://observability.mastra.ai/api/observability/metrics/aggregate" \
  -X POST \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" \
  -H "Content-Type: application/json" \
  --data '{"name":["mastra_model_total_input_tokens","mastra_model_total_output_tokens"],"aggregation":"sum","filters":{"timestamp":{"start":"2026-09-13T00:00:00Z","end":"2026-10-13T00:00:00Z"}},"comparePeriod":"previous_period"}' | jq

filters.timestamp is optional. If you omit start and end, the query covers all retained data. comparePeriod requires both start and end. Without them, the previous-period fields are null.

The API returns 401 for invalid credentials, 403 for organization authorization failures, and 400 for malformed query arguments or JSON bodies.

MastraClient

MastraClient from @mastra/client-js exposes the analytics and discovery methods. Set baseUrl to the region's host without the /api/observability path:

import { MastraClient } from '@mastra/client-js'

const mastraClient = new MastraClient({
  baseUrl: 'https://observability.mastra.ai',
  headers: {
    Authorization: `Bearer ${process.env.MASTRA_PLATFORM_ACCESS_TOKEN}`,
    'X-Mastra-Project-Id': process.env.MASTRA_PROJECT_ID!,
  },
})

const result = await mastraClient.getMetricAggregate({
  name: ['mastra_model_total_input_tokens', 'mastra_model_total_output_tokens'],
  aggregation: 'sum',
})

CLI

The mastra api metric commands target the United States endpoint by default. Pass --url to query the European Union region:

mastra api --url https://observability.eu.mastra.ai metric aggregate '<json>'

Gateway proxy endpoints

Visit the Gateway documentation for more details.