GET /run/{id}

[PGijsbers]

[saathviksheerla]

Hi @PGijsbers, I'd like to implement GET /run/{id}.
I've studied the existing tasks endpoint implementation and have a clear picture of the expected response from the PHP API. Could I be assigned to this?

[PGijsbers]

Hi @saathviksheerla, thanks for the interest! The reason this isn't marked as a good first issue is that it might involve complex database interactions and review time will be slow as we also need to analyze the PHP API. It's likely some discussion points may arise before having a consensus on how to migrate the endpoint. If you want to help with this issue, the first step would be to expand the description in this issue.

The documentation of the PHP-based endpoint is sometimes unavailable or quite limited, and does not always specify all behavior. Implementation-wise, it’s not always immediately obvious how it interacts with the database, either. It would be very helpful for this issue to include:

• a reference link to the PHP implementation of the endpoint on the openml repository.
• a quick write-up about how it interacts with the database. E.g., which tables/columns are referenced or written to, and how they translate to fields in the server responses.
• Any possible odd behaviors (or bugs) that can be observed that we should avoid, or discuss before implementation.
• a high level overview of the different steps of the endpoint (from the top of my head, but likely missing some stuff: check the user exists, check the flow exists, check predictions can be parsed (?), store predictions and update the database with a reference, add the run to the database).

[saathviksheerla]

Thank you for the detailed response @PGijsbers ! I'll start by exploring the PHP implementation and the database interactions, and put together a thorough write-up in the issue. Looking forward to working on this!

[saathviksheerla]

Description for GET /run/{id} — Issue #37

I've studied the PHP implementation and traced all database interactions.
Here is a full write-up covering the four points requested.

---

1. PHP Reference

The endpoint is handled by the run() private method:
https://github.com/openml/OpenML/blob/develop/openml_OS/models/api/v1/Api_run.php#L486

The routing entry point is bootstrap(), which dispatches to run($run_id)
when a numeric path segment is received via GET or POST request.

---

2. Database Interactions

The response is assembled from multiple tables across two databases
(openml_expdb and openml). Below is a full mapping of each table
to its corresponding response fields, verified against the local test database.

run (openml_expdb)

The core table. Everything starts here.

Column	Type	→ Response field
rid	int unsigned PK	run_id
uploader	mediumint unsigned	uploader (ID), used to fetch name
setup	int unsigned FK	used to fetch setup record
task_id	int	task_id
error_message	text	error (empty array [] if NULL)

algorithm_setup (openml_expdb)

Fetched via run.setup = algorithm_setup.sid.

Column	→ Response field
sid	setup_id
implementation_id	flow_id (also used to fetch flow name)
setup_string	setup_string

Confirmed for run 24: sid=2, implementation_id=19,
setup_string="Python_3.10.5. Sklearn_1.2.2. NumPy_1.26.0. SciPy_1.11.2."

implementation (openml_expdb)

Fetched via algorithm_setup.implementation_id = implementation.id.

Column	→ Response field
id	flow_id
fullName	flow_name

input + input_setting (openml_expdb)

Joined to produce parameter_setting[]. These two tables together
answer: "what parameters were used, with what values, for this setup?"

SELECT i.name, i.implementation_id, s.value
FROM input i, input_setting s
WHERE i.id = s.input_id AND setup = {sid}

Source column	→ Response field
input.name	parameter_setting[].name
input.implementation_id	parameter_setting[].component
input_setting.value	parameter_setting[].value

task + task_type (openml_expdb)

SELECT tt.name 
FROM task t, task_type tt
WHERE t.ttid = tt.ttid AND t.task_id = {task_id}

→ task_type in response (e.g. "Supervised Classification")

task_inputs (openml_expdb)

SELECT * FROM task_inputs
WHERE task_id = {task_id} AND input = 'evaluation_measures'

→ task_evaluation_measure in response.

run_tag (openml_expdb)

Filtered by id = run_id.

Column	→ Response field
tag	tag[]

Confirmed for run 24: ["openml-python", "Sklearn_1.2.2."]

input_data (openml_expdb)

Links a run to the dataset it was executed on. PK is (run, data).

Column	→ Response field
data	input_data.dataset.did

Confirmed for run 24: data=20 → matches "did": "20" (diabetes dataset).

runfile (openml_expdb)

Stores output files attached to a run. PK is (source, field).

Column	→ Response field
file_id	output_data.file[].file_id
field	output_data.file[].name (e.g. "description", "predictions")

Confirmed for run 24: file_id=182 (description.xml), file_id=183 (predictions.arff).

evaluation + math_function (openml_expdb)

Evaluation metric names are not stored directly — evaluation stores
function_id which must be resolved via math_function.

SELECT m.name, e.value, e.array_data
FROM evaluation e
JOIN math_function m ON e.function_id = m.id
WHERE e.source = {run_id} AND e.evaluation_engine_id = 1

Column	→ Response field
math_function.name	output_data.evaluation[].name
evaluation.value	output_data.evaluation[].value
evaluation.array_data	output_data.evaluation[].array_data

Confirmed for run 24: function_id=4 → area_under_roc_curve,
function_id=17 → f_measure.

users (openml — separate database)

The uploader's name lives in a separate database (openml, not openml_expdb).
Fetched via run.uploader = users.id.

Column	→ Response field
first_name + last_name	uploader_name (concatenated with space)

---

3. Quirks and Behaviors Worth Discussing

a) Hardcoded evaluation engine ID

The PHP hardcodes $weka_engine_id = 1 when fetching evaluations:

# TODO: currently, by default we get weka evaluation results
$run->eval_data = $this->Run_evaluated->getById(
    array($run_id, $this->weka_engine_id)
);

This means only evaluations from engine ID 1 are returned. The PHP
codebase itself marks this with a TODO. Should the Python implementation
replicate this behavior, make the engine configurable, or return
evaluations from all engines?

b) did: "-1" in output files

The PHP response includes "did": "-1" for each entry in
output_data.file[]. This value does not originate from the runfile
table (which has no did column), nor from the output_data table
(which is empty for run 24). It appears to be hardcoded in the PHP
XML response template. Should the Python implementation include this
field, omit it, or handle it differently?

c) Error codes mismatch with OpenAPI documentation

The @OA docstring on the endpoint declares error codes 220 and 221,
but the actual PHP implementation throws 235 (missing ID) and 236 (run not found).
Since FastAPI handles missing path parameters at the routing level,
only error 236 (run not found) is relevant for the Python implementation.

d) No visibility or authentication check

Unlike the dataset endpoint, GET /run/{id} performs no visibility
or ownership check. Any run is returned to any requester regardless
of authentication. This appears intentional but is worth confirming
before implementing.

e) task_evaluation_measure set to empty string when absent

When no evaluation_measures input exists for the task, PHP sets
$run->task_evaluation = "" rather than null or omitting the field.
The Python implementation should define consistent behavior here.

f) Cross-database query for uploader name

uploader_name is the only response field that requires querying the
openml database (not openml_expdb). This needs to be accounted for
in the Python database layer, similar to how other endpoints handle it.

---

4. High-Level Steps

1. Fetch core run record from run — error 236 if not found
2. Fetch uploader name from users table (openml DB) via run.uploader
3. Fetch setup record from algorithm_setup via run.setup
4. Fetch flow name from implementation via algorithm_setup.implementation_id
5. Fetch parameter settings via JOIN of input + input_setting on setup.sid
6. Fetch task type via JOIN of task + task_type on run.task_id
7. Fetch task evaluation measure from task_inputs where input = 'evaluation_measures'
8. Fetch tags from run_tag where id = run_id
9. Fetch input dataset from input_data where run = run_id
10. Fetch output files from runfile where source = run_id
11. Fetch evaluations from evaluation JOIN math_function where source = run_id
12. Assemble and return full response

[OA]

i apologize for declaring error codes

[PGijsbers]

3. Quirks and Behaviors Worth Discussing

a) Hardcoded evaluation engine ID
Should the Python implementation replicate this behavior, make the engine configurable, or return evaluations from all engines?

Making it configurable to a list of identifiers would be good. We will likely rewrite the evaluation engine sometime in the next year, and the newer version will have its own identifier, so we would need to make the change by then anyway.

b) did: "-1" in output files
Should the Python implementation include this field, omit it, or handle it differently?

Omit it. It's already marked deprecated 9 years ago. I believe the idea was that run outputs could create new datasets, but I don't see this idea going anywhere.

c) Error codes mismatch with OpenAPI documentation

Correct. There is no need to shoe-horn the 235 code back in. For the 236 code (and any other code), use the RFC9457 style errors as in src/errors.py with the old value set to the code custom field to ease migration efforts.

d) No visibility or authentication check

Correct. There is no support yet for private runs on an API level (though the database does include the column).
That is fine for now.

e) task_evaluation_measure set to empty string when absent

Correct. For single value fields, we now omit them if they are null/empty.

f) Cross-database query for uploader name

Correct. There are plans to revise the database design and make use of only a single database, but our plan is to tackle that when PHP has successfully sunset. So for now, separate queries is fine. In general, it might even be preferred to have a few simpler queries rather than one more complex one (even when they query the same database). Our focus right now is correctness. The PHP API seems to retrieve data through several roundtrips and we haven't really seen performance issues related to this endpoint.

[saathviksheerla]

Thanks for the clarification @PGijsbers , I will work on this and raise a PR soon, thanks!