# MiroFish API Endpoints for Monitoring Simulation Profiles in Real-Time > Access MiroFish API endpoints like /api/simulation//profiles/realtime to stream Agent Profile data for live monitoring during background generation tasks. - Repository: [BaiFu/mirofish](https://github.com/666ghj/mirofish) - Tags: api-reference - Published: 2026-02-23 --- **MiroFish exposes a dedicated GET endpoint at `/api/simulation//profiles/realtime` that streams current Agent Profile data while background generation tasks are still running, enabling live monitoring of Reddit or Twitter profile creation progress without blocking on the SimulationManager.** The MiroFish platform provides specialized API endpoints for monitoring simulation profiles in real-time, allowing developers to track Agent Profile generation as it happens rather than waiting for batch completion. These endpoints read directly from the simulation data directory, bypassing the `SimulationManager` to provide immediate access to partially generated files while the background task is still active. This article examines the specific endpoint implementations, request parameters, and response structures available in the `666ghj/mirofish` repository. ## Real-Time Profile Monitoring Endpoint ### Endpoint Specification The primary endpoint for real-time profile monitoring accepts GET requests at the following URL pattern: ``` GET /api/simulation//profiles/realtime ``` **Query Parameters:** - `platform` (string, optional): Specifies the social media platform to monitor. Accepts `reddit` (default) or `twitter`. **Path Parameters:** - `simulation_id` (string, required): The unique identifier for the running simulation instance. ### How It Works According to the source code in [`backend/app/api/simulation.py`](https://github.com/666ghj/mirofish/blob/main/backend/app/api/simulation.py) (lines 1023-1122), the endpoint implements the following logic: 1. **Platform Detection**: The handler checks the `platform` query parameter to determine whether to read [`reddit_profiles.json`](https://github.com/666ghj/mirofish/blob/main/reddit_profiles.json) or `twitter_profiles.csv` from the simulation directory. 2. **Direct File Access**: The endpoint constructs the file path using `Config.OASIS_SIMULATION_DATA_DIR//` and attempts to read the profile file directly, bypassing the `SimulationManager` to avoid blocking on active generation tasks. 3. **Safe Parsing**: If the file is partially written or locked, the parser catches IO errors and returns an empty list, allowing clients to poll safely without encountering 500 errors. 4. **State Inspection**: The endpoint reads [`state.json`](https://github.com/666ghj/mirofish/blob/main/state.json) to check the `status` field; when it equals `"preparing"`, the response includes `"is_generating": true`. ### Response Payload Structure The endpoint returns a JSON object with the following structure: ```json { "success": true, "data": { "simulation_id": "sim_12345", "platform": "reddit", "count": 15, "total_expected": 93, "is_generating": true, "file_exists": true, "file_modified_at": "2025-12-04T18:20:00", "profiles": [] } } ``` **Key Fields:** - `count`: Current number of parsed profiles in the file. - `total_expected`: Total number of profiles to be generated based on simulation configuration. - `is_generating`: Boolean flag indicating whether the background generation task is still active. - `profiles`: Array containing the actual profile objects (Reddit or Twitter format). ## Related Real-Time Configuration Endpoint MiroFish also provides a companion endpoint for monitoring configuration file generation: ``` GET /api/simulation//config/realtime ``` This endpoint follows the same direct-file-access pattern, returning the current simulation configuration file while it is being generated. It is useful when you need to verify that configuration parameters have been written correctly before profile generation completes. ## Implementation Details The real-time monitoring functionality is implemented in the following source files within the `666ghj/mirofish` repository: - **[`backend/app/api/simulation.py`](https://github.com/666ghj/mirofish/blob/main/backend/app/api/simulation.py)** (lines 1023-1122): Contains the Flask route definition and handler logic for the `/profiles/realtime` endpoint. This includes file parsing, error handling, and state inspection. - **[`backend/app/api/__init__.py`](https://github.com/666ghj/mirofish/blob/main/backend/app/api/__init__.py)** (lines 8-9): Creates and registers the `simulation_bp` Blueprint that mounts the routes under the `/api/simulation` prefix. - **[`backend/app/config.py`](https://github.com/666ghj/mirofish/blob/main/backend/app/config.py)**: Defines the `OASIS_SIMULATION_DATA_DIR` constant used to construct file paths for direct disk access. - **[`backend/app/services/simulation_manager.py`](https://github.com/666ghj/mirofish/blob/main/backend/app/services/simulation_manager.py)**: Manages the simulation lifecycle. Notably, the real-time endpoints bypass this manager to avoid blocking on active tasks. ## Code Examples ### Basic cURL Request Monitor Reddit profiles for a specific simulation: ```bash curl -X GET "http://localhost:5000/api/simulation/sim_abc123/profiles/realtime?platform=reddit" ``` ### Python Polling Client The following Python script polls the endpoint every 5 seconds until profile generation completes: ```python import time import requests API_ROOT = "http://localhost:5000/api/simulation" SIM_ID = "sim_abc123" def get_realtime_profiles(): r = requests.get( f"{API_ROOT}/{SIM_ID}/profiles/realtime", params={"platform": "reddit"} ) r.raise_for_status() return r.json()["data"] while True: data = get_realtime_profiles() print(f"Got {data['count']} / {data.get('total_expected', '?')} profiles") if not data["is_generating"]: print("Generation completed") break time.sleep(5) ``` ### Fetching Configuration Status To monitor the configuration file generation alongside profiles: ```bash curl -X GET "http://localhost:5000/api/simulation/sim_abc123/config/realtime" ``` ## Summary - MiroFish provides the **`/api/simulation//profiles/realtime`** endpoint for live monitoring of Agent Profile generation. - The endpoint supports both **Reddit** ([`reddit_profiles.json`](https://github.com/666ghj/mirofish/blob/main/reddit_profiles.json)) and **Twitter** (`twitter_profiles.csv`) platforms via the `platform` query parameter. - It reads files directly from the simulation data directory, bypassing the `SimulationManager` to provide non-blocking access to partially generated files. - The response includes metadata such as `count`, `total_expected`, `is_generating`, and the actual profile data. - A companion **`/config/realtime`** endpoint offers the same real-time access for simulation configuration files. ## Frequently Asked Questions ### What is the primary endpoint for monitoring simulation profiles in real-time? The primary endpoint is **`GET /api/simulation//profiles/realtime`**. This endpoint returns the current state of Agent Profile files while they are being generated, including metadata about generation progress and the actual profile data parsed from [`reddit_profiles.json`](https://github.com/666ghj/mirofish/blob/main/reddit_profiles.json) or `twitter_profiles.csv`. ### How does the endpoint handle incomplete or locked profile files? The endpoint implements safe parsing logic in [`backend/app/api/simulation.py`](https://github.com/666ghj/mirofish/blob/main/backend/app/api/simulation.py) that catches IO errors when files are partially written or locked by the background generation process. When parsing fails, it returns an empty list for the profiles field rather than crashing, allowing clients to poll continuously without encountering 500 errors. ### Can I monitor both Reddit and Twitter profiles simultaneously? Yes, by using the `platform` query parameter. Set `platform=reddit` (the default) to monitor [`reddit_profiles.json`](https://github.com/666ghj/mirofish/blob/main/reddit_profiles.json), or set `platform=twitter` to monitor `twitter_profiles.csv`. To track both platforms simultaneously, your client must make separate requests to the same endpoint with different platform parameters and merge the results. ### Where is the endpoint logic implemented in the MiroFish codebase? The route handler is implemented in **[`backend/app/api/simulation.py`](https://github.com/666ghj/mirofish/blob/main/backend/app/api/simulation.py)** between lines 1023 and 1122, where the Flask route reads files directly from `Config.OASIS_SIMULATION_DATA_DIR`. The route is registered via the `simulation_bp` Blueprint defined in **[`backend/app/api/__init__.py`](https://github.com/666ghj/mirofish/blob/main/backend/app/api/__init__.py)** (lines 8-9).