# Read Trial

Retrieves information about a specific optimization trial in globalMOO.

## Endpoint

`GET /trials/{trial_id}`

## Path Parameters

| Parameter | Type    | Required | Description                    |
| --------- | ------- | -------- | ------------------------------ |
| trial\_id | integer | Yes      | Unique identifier of the trial |

## Response Fields

| Field         | Type                  | Description                              |
| ------------- | --------------------- | ---------------------------------------- |
| id            | integer               | Unique identifier for the trial          |
| project\_id   | integer               | ID of the parent project                 |
| status        | string                | Current status (see Status Values below) |
| outputs       | array\[array\[float]] | Array of output case arrays              |
| output\_count | integer               | Number of outputs per case               |
| created\_at   | string                | Creation timestamp (ISO 8601)            |
| updated\_at   | string                | Last update timestamp (ISO 8601)         |

```json
{
    "id": 123,
    "project_id": 456,
    "status": "active",
    "output_count": 3,
    "outputs": [
        [1.2, 3.4, 5.6],
        [7.8, 9.0, 1.2],
        [3.4, 5.6, 7.8]
    ],
    "created_at": "2025-01-31T10:00:00.000Z",
    "updated_at": "2025-01-31T10:00:00.000Z"
}
```

## Examples

{% tabs %}
{% tab title="Python" %}
```python
from globalmoo import Client

client = Client(api_key="your-api-key")
trial = client.read_trial(trial_id=123)

print(f"Trial status: {trial.status}")
print(f"Output count: {trial.output_count}")
for outputs in trial.outputs:
    print(f"Outputs: {outputs}")
```
{% endtab %}

{% tab title="Node.js" %}
```javascript
const { Client } = require('globalmoo');

const client = new Client('your-api-key');
const trial = await client.readTrial(123);

console.log(`Trial status: ${trial.status}`);
console.log(`Output count: ${trial.outputCount}`);
trial.outputs.forEach(outputs => {
    console.log(`Outputs: ${outputs.join(', ')}`);
});
```
{% endtab %}

{% tab title="PHP" %}
```php
$client = new Client("your-api-key");

$trial = $client->readTrial(123);

echo "Trial status: " . $trial->status . "\n";
echo "Output count: " . $trial->outputCount . "\n";
foreach ($trial->outputs as $outputs) {
    echo "Outputs: " . implode(", ", $outputs) . "\n";
}
```
{% endtab %}
{% endtabs %}

## Response Example

```json
{
    "id": 123,
    "project_id": 456,
    "status": "completed",
    "output_count": 3,
    "outputs": [
        [1.234, 3.456, 5.678],
        [7.890, 9.012, 1.234],
        [3.456, 5.678, 7.890]
    ],
    "created_at": "2025-01-31T10:00:00.000Z",
    "updated_at": "2025-01-31T10:15:00.000Z"
}
```

## Error Responses

| Status Code | Description                             |
| ----------- | --------------------------------------- |
| 401         | Unauthorized - Invalid API key          |
| 404         | Trial not found                         |
| 429         | Too many requests - Rate limit exceeded |
| 500         | Internal server error                   |

## Status Values

Possible trial status values:

* `active` - Trial is currently running
* `completed` - Trial has finished successfully
* `failed` - Trial encountered an error
* `stopped` - Trial was manually stopped

## Validation Rules

* Trial ID must be a positive integer
* Trial must exist
* output\_count matches the number of values in each output array
* All output values must be valid floating point numbers
