MiroFish API Endpoints for Monitoring Simulation Profiles in Real-Time

MiroFish exposes a dedicated GET endpoint at /api/simulation/<simulation_id>/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/<simulation_id>/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 (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 or twitter_profiles.csv from the simulation directory.

2. Direct File Access: The endpoint constructs the file path using Config.OASIS_SIMULATION_DATA_DIR/<simulation_id>/ 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 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:

{
  "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/<simulation_id>/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 (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 (lines 8-9): Creates and registers the simulation_bp Blueprint that mounts the routes under the /api/simulation prefix.

• 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: 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:

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:

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:

curl -X GET "http://localhost:5000/api/simulation/sim_abc123/config/realtime"

Summary

• MiroFish provides the /api/simulation/<simulation_id>/profiles/realtime endpoint for live monitoring of Agent Profile generation.
• The endpoint supports both Reddit (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/<simulation_id>/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 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 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, 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 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 (lines 8-9).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}