Implementation:Mage ai Mage ai Mode Client
| Knowledge Sources | |
|---|---|
| Domains | Data_Integration, Mode, API |
| Last Updated | 2026-02-09 00:00 GMT |
Overview
Concrete HTTP client for making authenticated requests to the Mode Analytics API, provided by the Mage Mode source connector.
Description
The ModeClient class manages all HTTP communication with the Mode Analytics API at https://app.mode.com/api/{workspace}. It authenticates using HTTP Basic Auth with Base64-encoded access_token:password credentials. The client is implemented as a context manager, verifying the access token on entry by hitting the /spaces endpoint and closing the session on exit. Rate limiting is enforced via the Singer @utils.ratelimit(1000, 60) decorator. It uses Singer metrics.http_request_timer for request timing instrumentation. A comprehensive exception hierarchy maps HTTP status codes (400-500) to specific error classes. Configurable request timeout defaults to 300 seconds.
Usage
Used internally by Mode stream classes. Requires access_token, password, workspace, and optionally request_timeout and user_agent.
Code Reference
Source Location
- Repository: mage-ai
- File:
mage_integrations/mage_integrations/sources/mode/client.py - Lines: 1-252
Signature
class ModeClient(object):
def __init__(self,
access_token,
password,
workspace,
config_request_timeout,
user_agent=None):
Import
from mage_integrations.sources.mode.client import ModeClient
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| access_token | str | Yes | API access token for Mode authentication |
| password | str | Yes | API password for Mode authentication (combined with access_token for Basic Auth) |
| workspace | str | Yes | Mode workspace name, used to construct the base URL |
| config_request_timeout | float/str | Yes | Request timeout in seconds (defaults to 300 if falsy) |
| user_agent | str | No | Optional User-Agent header value |
Outputs
| Name | Type | Description |
|---|---|---|
| response | dict | Parsed JSON response from the Mode API |
Key Methods
| Method | Description |
|---|---|
check_access_token() |
Validates credentials by querying /spaces. Uses Base64-encoded Basic Auth.
|
request(method, path, url, **kwargs) |
Core request method with rate limiting, metric timing, Basic Auth headers, and error handling. |
get(path, **kwargs) |
Convenience wrapper for GET requests with logging. |
post(path, **kwargs) |
Convenience wrapper for POST requests. |
perform(method, path, **kwargs) |
Dispatches to get or post based on method string.
|
Usage Examples
from mage_integrations.sources.mode.client import ModeClient
with ModeClient(
access_token='your_mode_token',
password='your_mode_password',
workspace='your-workspace',
config_request_timeout=300,
) as client:
spaces = client.get('spaces')
reports = client.get('spaces/my-space/reports')