# mabl API reference Documentation

## API Reference
- [Authentication](https://api.help.mabl.com/reference/authentication.md): How to authenticate mabl API requests
- [mabl API reference](https://api.help.mabl.com/reference/intro-to-the-mabl-api.md): Introduction to the mabl API
- [mabl resource IDs](https://api.help.mabl.com/reference/mabl-resource-ids.md): Overview of mabl resource IDs in API requests and responses
- [Pagination](https://api.help.mabl.com/reference/pagination.md): How to retrieve results from paginated endpoints
- [Response types](https://api.help.mabl.com/reference/response-types.md): Overview of HTTP response codes and how to troubleshoot errors
- [Create application](https://api.help.mabl.com/reference/createapplication.md): Create a new application
- [Get application by ID](https://api.help.mabl.com/reference/getapplication.md): Get application information by ID
- [Get applications by workspace](https://api.help.mabl.com/reference/queryapplications.md): Get all applications in a workspace
- [Remove application](https://api.help.mabl.com/reference/removeapplication.md): Remove an application
- [Update application](https://api.help.mabl.com/reference/updateapplication.md): Update an existing application
- [Create Credentials](https://api.help.mabl.com/reference/createcredentials.md): Create new credentials
- [Get Credentials](https://api.help.mabl.com/reference/getcredentials.md): Retrieve complete information about credentials. Includes plain text secrets. NOTE: TOTP secret keys are never returned to the client
- [Query Credentials](https://api.help.mabl.com/reference/querycredentials.md): Query for credentials. Decrypted credential provided only if `with_secrets` flag set `true` and is not available for cloud-only credentials.
- [Remove Credentials](https://api.help.mabl.com/reference/removecredentials.md): Remove credentials
- [Update Credentials](https://api.help.mabl.com/reference/updatecredentials.md): Update existing credentials. NOTE: TOTP tokens will be unchanged if NULL passed. They will be cleared if '' (blank string) is passed.
- [Create database connection](https://api.help.mabl.com/reference/createdatabaseconnection.md): Create a new database connection
- [Remove database connection](https://api.help.mabl.com/reference/deletedatabaseconnection.md): Remove an existing database connection. Warning: Deleting an existing database connection will cause associated queries to no longer function. We recommend reviewing all associated queries and tests that use them in the mabl UI before proceeding.
- [Get database connection](https://api.help.mabl.com/reference/getdatabaseconnection.md): Get database connection information by ID
- [Get database connections by workspace](https://api.help.mabl.com/reference/querydatabaseconnections.md): Returns database connections configured in a workspace
- [Update database connection](https://api.help.mabl.com/reference/updatedatabaseconnection.md): Update an existing database connection
- [Create DataTable](https://api.help.mabl.com/reference/createdatatable.md): Create a DataTable in a workspace. The maximum number of scenarios for a DataTable is 1000.
- [Create Scenario](https://api.help.mabl.com/reference/createscenario.md): Create and add a new scenario to a DataTable
- [Create variable name](https://api.help.mabl.com/reference/createvariablename.md): Add a new variable to an existing DataTable. The variable is appended to all scenarios with an empty string as the default value. Use the [update scenario](https://api.help.mabl.com/reference/putscenario) endpoint to assign specific values per scenario.
- [Get DataTable](https://api.help.mabl.com/reference/getdatatable.md): Retrieve metadata about a specific DataTable. To get scenarios for a specific DataTable, use the [get scenarios](https://api.help.mabl.com/reference/queryscenarios) endpoint.
- [Get Scenario](https://api.help.mabl.com/reference/getscenario.md): Retrieve the variable values for a specific DataTable scenario
- [Get variable names](https://api.help.mabl.com/reference/getvariablenames.md): Get the current variable names for a DataTable
- [Update DataTable](https://api.help.mabl.com/reference/putdatatable.md): Update the DataTable name and/or description. Use the [update variables](https://api.help.mabl.com/reference/updatevariablename) and [update scenario](https://api.help.mabl.com/reference/putscenario) endpoints to update the contents of a DataTable.
- [Update Scenario](https://api.help.mabl.com/reference/putscenario.md): Update a scenario and/or its variable values
- [Get DataTables](https://api.help.mabl.com/reference/querydatatables.md): Query for DataTables in a workspace
- [Get Scenarios](https://api.help.mabl.com/reference/queryscenarios.md): Retrieve scenarios, variable values, and scenario IDs associated with a DataTable
- [Remove Scenario](https://api.help.mabl.com/reference/removescenario.md): Delete a specific scenario from a DataTable using its scenario ID
- [Delete variable name](https://api.help.mabl.com/reference/removevariablename.md): Remove an existing variable name and its associated values from all scenarios in the DataTable
- [Update variable name](https://api.help.mabl.com/reference/updatevariablename.md): Update an existing variable's name and apply it to all scenarios in the DataTable
- [Create environment](https://api.help.mabl.com/reference/createenvironment.md): Create a new environment
- [Get Environment by ID](https://api.help.mabl.com/reference/getenvironment.md): Get environment information by ID
- [Get environments by workspace](https://api.help.mabl.com/reference/queryenvironments.md): Get all environments in a workspace
- [Remove environment](https://api.help.mabl.com/reference/removeenvironment.md): Remove an environment
- [Update environment](https://api.help.mabl.com/reference/updateenvironment.md): Update an existing environment. **Note** - when you use the update environment endpoint to update environment variables, you completely replace any existing variables.
- [Get a deployment result summary](https://api.help.mabl.com/reference/getexecutionresultforevent.md): Retrieve information about the plan runs executed using the deployment events API.
- [Trigger tests on deployment](https://api.help.mabl.com/reference/ondeploy.md): Create a deployment event to trigger a parallel run of all active plans that meet specified conditions, including application, environment, and plan label. Learn more in [the docs](https://help.mabl.com/hc/en-us/articles/17780788992148).
- [Query Deployment Events](https://api.help.mabl.com/reference/querydeploymentevents.md): Used to query deployment events
- [Query Deployment Events by revision](https://api.help.mabl.com/reference/querydeploymenteventsbyrevision.md): Used to query deployment events by revision (commit ID/SHA)
- [Get flow metadata](https://api.help.mabl.com/reference/getflowmetadata.md): Get the unversioned metadata of an existing flow
- [Update flow metadata only](https://api.help.mabl.com/reference/updateflowmetadata.md): Update the unversioned metadata of an existing flow
- [Create issue](https://api.help.mabl.com/reference/createissue.md)
- [Get issue](https://api.help.mabl.com/reference/getissue.md)
- [Query workspace issues](https://api.help.mabl.com/reference/queryissuesbyworkspaceid.md)
- [Remove issue](https://api.help.mabl.com/reference/removeissue.md)
- [Updates issue](https://api.help.mabl.com/reference/updateissue.md): Updates an issue and marks it to indicate that it needs to be synced to the issue tracker.
- [Query Link Agents](https://api.help.mabl.com/reference/querylinkagents.md): Query for Link Agents by workspace ID
- [Download Link Agent](https://api.help.mabl.com/reference/redirecttolatestdistribution.md): Redirect the client to download the latest Link Agent distribution
- [Terminate Link Agent](https://api.help.mabl.com/reference/terminatelinkagent.md): Send a shutdown signal to a specific Link Agent. When invoked, the Link Agent process will shut down and will not attempt to reconnect.
- [Delete Link Label](https://api.help.mabl.com/reference/deletelinkstack.md): Delete all link assets associated with the provided label (Link Agent name).  Use this to clean up Link Tunnels created for ephemeral test environments.
- [Query Link Labels](https://api.help.mabl.com/reference/querylinklabels.md): Get all Link labels (Link Agent names) associated with a workspace.
- [Create Mailbox](https://api.help.mabl.com/reference/createpermanentmailbox.md): Create new mabl Mailbox address
- [Delete Mailbox](https://api.help.mabl.com/reference/deletemailboxaddress.md): Delete a Mailbox by ID
- [Get Mailbox](https://api.help.mabl.com/reference/getmailboxaddress.md): Get a Mailbox by email address or ID
- [Get information on Mailboxes by workspace ID](https://api.help.mabl.com/reference/querymailboxesinworkspace.md): Get permanent email addresses in workspace and number of remaining allowed permanent Mailboxes for workspace
- [Update Mailbox](https://api.help.mabl.com/reference/updatemailboxaddress.md): Update the name and description of a permanent Mailbox. The email address cannot be changed.
- [Update Mailbox status](https://api.help.mabl.com/reference/updatemailboxstatus.md): Enable or disable a Mailbox
- [Invite user to workspace](https://api.help.mabl.com/reference/createorganizationinvitation.md): Create link or email based workspace invite. For email invites, invite emails are sent to the invited users.
- [Create an export of test run artifacts](https://api.help.mabl.com/reference/createtestrunartifactexport.md): Initiate an asynchronous export of specified test run artifacts, such as screenshots or HAR logs. This endpoint returns an export ID. Use the export ID with the [get export](https://api.help.mabl.com/reference/gettestrunartifactexport) endpoint to retrieve the download URL.
- [Get test run summaries over a time range](https://api.help.mabl.com/reference/getbatchtestrunresults.md): Get results for a batch of test runs, with filtering available for time range, test/plan labels, test ID, plan ID, application ID, environment ID, and status.
- [Get a plan run summary](https://api.help.mabl.com/reference/getplanrunresult.md): Retrieve detailed information about this plan run, including each of its test runs.
- [Get a test run artifact export](https://api.help.mabl.com/reference/gettestrunartifactexport.md): Get test run artifact exports using the export ID returned by the [create export](https://api.help.mabl.com/reference/createtestrunartifactexport) endpoint. Once the export status is completed, the response includes a temporary signed URL for downloading the artifact ZIP file.
- [Get a test run summary](https://api.help.mabl.com/reference/gettestrunresult.md): Retrieve detailed information about a test run and its outcome.
- [Query account execution seconds](https://api.help.mabl.com/reference/queryaccountexecutionseconds.md): Same as `/workspaces/{workspace_id}/reports/usage/executionSeconds` but aggregates across every active workspace the authenticated caller has access to within the account. Use this for account-wide billing or utilization reports, or pair with `group_by=workspace` to produce a per-workspace breakdown of execution seconds.  Scope to one workspace by passing its identifier as the `workspace_id` query parameter; the caller must have access to that workspace. All filter, granularity, `group_by`, and time-range rules are identical to the workspace-level endpoint. All timestamps are Unix epoch milliseconds.
- [Query account daily maximum concurrent test runs](https://api.help.mabl.com/reference/queryaccountmaxtestrunconcurrency.md): Same as `/workspaces/{workspace_id}/reports/usage/maxTestRunConcurrency` but returns one block per active workspace the authenticated caller has access to within the account. Each workspace's response includes its own `configured_test_run_concurrency_limit`, which can differ across workspaces in the same account (for example, one workspace might have a higher browser quota than another). Use this endpoint for account-wide capacity dashboards or to flag which workspaces are running near their limit.  Scope to a single workspace by passing its identifier as the `workspace_id` query parameter while still authenticating with account-level credentials. Time range, `test_type`, and default-range semantics are identical to the workspace-level endpoint.
- [Query account test run counts](https://api.help.mabl.com/reference/queryaccounttestruncounts.md): Same as `/workspaces/{workspace_id}/reports/usage/testRunCounts` but aggregates across every active workspace the authenticated caller has access to within the account. Use this endpoint for account-wide usage dashboards where you want a single aggregated bucket per time period, or pair it with `group_by=workspace` to produce a per-workspace breakdown of test run counts.  To scope the query to a single workspace within the account (for example, to reuse the same account-level API key while drilling into one workspace), pass its identifier as the `workspace_id` query parameter. When `workspace_id` is provided, the caller must still have access to that workspace.  All filter (`application_id`, `plan_id`, `test_type`), granularity, `group_by`, and time-range rules are identical to the workspace-level endpoint. All timestamps are Unix epoch milliseconds.
- [Retrieve activity feed entries](https://api.help.mabl.com/reference/queryactivityfeed.md): Query the activity feed for a workspace.
- [Query execution seconds](https://api.help.mabl.com/reference/queryworkspaceexecutionseconds.md): Retrieve total execution time for an active workspace, aggregated into time buckets. The `total_execution_seconds` field sums (end_time - start_time) across every completed run whose `start_time` falls within the bucket. In-flight runs (without a recorded end_time) are excluded both from this sum and from the `total_test_runs` count on this endpoint — consult `testRunCounts` if you want a count that includes in-flight runs.  Execution time is measured from the moment a run starts executing to the moment it completes (successfully or otherwise). It does not include time spent queued waiting for a runner. Useful for billing, capacity planning, or attributing compute cost to a specific team (via `application_id` or `plan_id`), test type, or time window.  All filter, granularity, and `group_by` semantics are identical to the `testRunCounts` endpoint. All timestamps are Unix epoch milliseconds, and bucket boundaries are aligned to UTC.
- [Query workspace daily maximum concurrent test runs](https://api.help.mabl.com/reference/queryworkspacemaxtestrunconcurrency.md): Retrieve the daily maximum number of simultaneously executing test runs in an active workspace, along with the workspace's configured test run concurrency limit for the same test type. The reported `max_test_run_concurrency` is computed as the maximum number of runs executing at any single instant during the day — not an average, not a count of runs started. If ten runs start and finish within the same minute but a different run was also executing for that minute, the maximum for that minute is eleven.  Use this endpoint to track how close a workspace is running to its purchased concurrency capacity, decide when to request a limit increase, identify load bursts, or correlate peak usage with customer-side deployment or traffic patterns. Compare the `max_test_run_concurrency` values against `configured_test_run_concurrency_limit` to see headroom.  Data is pre-aggregated from billable events by a background job that runs every 12 hours, so values for the current calendar day may be incomplete until the next aggregation cycle finishes. Time range cannot exceed 90 days. If `start_time` and `end_time` are both omitted, the endpoint returns the last 90 completed days ending at the start of the current UTC day.  The `configured_test_run_concurrency_limit` is resolved against the requested `test_type`. For `browser` (the default when unspecified), it is the sum of the workspace's Linux, macOS, and Windows browser quotas. For `api`, `mobile`, or `performance`, it is the single numeric quota for that resource. A workspace with no configured quota for a given test type returns `configured_test_run_concurrency_limit: 0`.
- [Query test run counts](https://api.help.mabl.com/reference/queryworkspacetestruncounts.md): Retrieve the count of test runs in an active workspace, aggregated into time buckets. Each bucket reports the total number of runs that started within the bucket window, as well as how many of those passed and how many failed or were terminated. Useful for plotting test activity over time, tracking reliability trends, and feeding external dashboards with per-day/week/month usage metrics.  Runs are counted by their `start_time`, not `end_time` — a long-running test that starts on day D and finishes on day D+1 is attributed to day D. In-flight runs (ones that have started but not yet completed) are included in `total_test_runs` and counted as `failed_test_runs` until they complete, since they have not yet succeeded.  Optional filters (`application_id`, `plan_id`, `test_type`) narrow the underlying row set. Optional `group_by` (`plan` or `application`) breaks each time bucket further into one bucket per group value, with the `group_id` field on each bucket identifying the dimension value.  All timestamps in requests and responses are Unix epoch milliseconds. Bucket boundaries are aligned to UTC; convert to local time on the client side if needed. Time range is capped by granularity: daily (90 days), weekly/monthly (400 days). Data is served live from the test run database, so results reflect runs completed within seconds of the request.
- [Get test metadata](https://api.help.mabl.com/reference/gettestmetadata.md): Get the unversioned metadata of an existing test
- [Update test metadata](https://api.help.mabl.com/reference/updatetestmetadata.md): Update the unversioned metadata of an existing test
- [Get workspace user](https://api.help.mabl.com/reference/getworkspaceuser.md): Retrieve a user in the context of a workspace. This will also retrieve high-level user information for any users that were historically in the workspace. Users not in the workspace will be filtered out.
- [Query users](https://api.help.mabl.com/reference/queryusers.md): Query for users