get-experiment-by-id
Retrieve experiment metadata and results by ID, including outputs, annotations, and evaluator scores for comparison against expected dataset outputs.
Instructions
Get an experiment by its ID.
The tool returns experiment metadata in the first content block and a JSON object with the experiment data in the second. The experiment data contains both the results of each experiment run and the annotations made by an evaluator to score or label the results, for example, comparing the output of an experiment run to the expected output from the dataset example.
Example usage: Show me the experiment results for experiment RXhwZXJpbWVudDo4
Expected return: Object containing experiment metadata and results. Example: { "metadata": { "id": "experimentid1234", "dataset_id": "datasetid1234", "dataset_version_id": "datasetversionid1234", "repetitions": 1, "metadata": {}, "project_name": "Experiment-abc123", "created_at": "YYYY-MM-DDTHH:mm:ssZ", "updated_at": "YYYY-MM-DDTHH:mm:ssZ" }, "experimentResult": [ { "example_id": "exampleid1234", "repetition_number": 0, "input": "Sample input text", "reference_output": "Expected output text", "output": "Actual output text", "error": null, "latency_ms": 1000, "start_time": "2025-03-20T12:00:00Z", "end_time": "2025-03-20T12:00:01Z", "trace_id": "trace-123", "prompt_token_count": 10, "completion_token_count": 20, "annotations": [ { "name": "quality", "annotator_kind": "HUMAN", "label": "good", "score": 0.9, "explanation": "Output matches expected format", "trace_id": "trace-456", "error": null, "metadata": {}, "start_time": "YYYY-MM-DDTHH:mm:ssZ", "end_time": "YYYY-MM-DDTHH:mm:ssZ" } ] } ] }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| experiment_id | Yes |
Implementation Reference
- The handler function that fetches the experiment metadata and JSON data using PhoenixClient APIs for the given experiment_id and returns a formatted JSON response as text content.async ({ experiment_id }) => { const [experimentMetadataResponse, experimentDataResponse] = await Promise.all([ client.GET("/v1/experiments/{experiment_id}", { params: { path: { experiment_id, }, }, }), client.GET("/v1/experiments/{experiment_id}/json", { params: { path: { experiment_id, }, }, }), ]); const text = JSON.stringify({ metadata: experimentMetadataResponse.data?.data, experimentResult: experimentDataResponse.data, }); return { content: [{ type: "text", text }], }; }
- js/packages/phoenix-mcp/src/experimentTools.ts:118-150 (registration)Registers the 'get-experiment-by-id' MCP tool on the server, specifying name, description, Zod input schema, and inline handler.server.tool( "get-experiment-by-id", GET_EXPERIMENT_DESCRIPTION, { experiment_id: z.string(), }, async ({ experiment_id }) => { const [experimentMetadataResponse, experimentDataResponse] = await Promise.all([ client.GET("/v1/experiments/{experiment_id}", { params: { path: { experiment_id, }, }, }), client.GET("/v1/experiments/{experiment_id}/json", { params: { path: { experiment_id, }, }, }), ]); const text = JSON.stringify({ metadata: experimentMetadataResponse.data?.data, experimentResult: experimentDataResponse.data, }); return { content: [{ type: "text", text }], }; } );
- js/packages/phoenix-mcp/src/index.ts:45-45 (registration)Top-level call to initializeExperimentTools which registers the 'get-experiment-by-id' tool among others on the MCP server.initializeExperimentTools({ client, server });
- Zod schema defining the input parameter 'experiment_id' as a string for the tool.experiment_id: z.string(), },