get_metric_samples
Retrieve raw metric samples within a specified time range from Fulcra Context MCP, including samples with intersecting ranges and timezone-adjusted timestamps.
Instructions
Retrieve the raw samples related to a given metric for the user during a specified period.
In cases where samples cover ranges and not points in time, a sample will be returned if any part of its range intersects with the requested range. For example, if start_time is 14:00 and end_time is 15:00, a sample covering 13:30-14:30 will be included. Result timestamps will include time zones. Always translate timestamps to the user's local time zone when this is known.
Args:
metric_name: The name of the metric to retrieve samples for. Use get_metrics_catalog to find available metrics.
start_time: The start of the time range (inclusive), as an ISO 8601 string or datetime object.
end_time: The end of the time range (exclusive), as an ISO 8601 string or datetime object.
Returns:
A JSON string representing a list of raw samples for the metric.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| metric_name | Yes | ||
| start_time | Yes | ||
| end_time | Yes |
Implementation Reference
- fulcra_mcp/main.py:377-406 (handler)The handler function for the 'get_metric_samples' MCP tool. It is registered via the @mcp.tool() decorator. Retrieves raw metric samples using FulcraAPI.metric_samples and formats the result as a JSON string.async def get_metric_samples( metric_name: str, start_time: datetime, end_time: datetime, ) -> str: """Retrieve the raw samples related to a given metric for the user during a specified period. In cases where samples cover ranges and not points in time, a sample will be returned if any part of its range intersects with the requested range. For example, if start_time is 14:00 and end_time is 15:00, a sample covering 13:30-14:30 will be included. Result timestamps will include time zones. Always translate timestamps to the user's local time zone when this is known. Args: metric_name: The name of the metric to retrieve samples for. Use `get_metrics_catalog` to find available metrics. start_time: The start of the time range (inclusive), as an ISO 8601 string or datetime object. end_time: The end of the time range (exclusive), as an ISO 8601 string or datetime object. Returns: A JSON string representing a list of raw samples for the metric. """ fulcra = get_fulcra_object() samples = fulcra.metric_samples( metric=metric_name, start_time=start_time, end_time=end_time, ) return ( f"Raw samples for {metric_name} from {start_time} to {end_time}: " + json.dumps(samples) )