Autoresearch

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

`GET`
`POST`
`GET`
`GET`
`POST`
`POST`
`POST`
`POST`
`POST`
`POST`

← Previous pageNext page →

List all autoresearch training runs

List and retrieve training runs for a pipeline.

A training run records the agent's search for a model: each iteration's recipe and holdout score, and the summary of the run once it completes.

Required API key scopes

autoresearch:read

Path parameters

pipeline_id
string

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/training_runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/".format(
        project_id=project_id,
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
      "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
      "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
      "task_url": "string",
      "status": "pending",
      "kickoff_reason": "explore",
      "agent_runtime_adapter": "string",
      "agent_model": "string",
      "agent_model_label": "string",
      "agent_reasoning_effort": "string",
      "iteration_budget": -2147483648,
      "iteration_count": 0,
      "best_holdout_score": 0,
      "summary": {
        "target_event": "string",
        "horizon_days": 0,
        "best_holdout_score": 0,
        "champion_promoted": true,
        "champion_model_class": "string",
        "kept_ladder": [
          {
            "iteration_number": 0,
            "holdout_score": 0,
            "model_class": "string",
            "agent_description": "string"
          }
        ],
        "dead_ends": [
          {
            "iteration_number": 0,
            "holdout_score": 0,
            "model_class": "string",
            "agent_description": "string"
          }
        ],
        "recommended_next": "string",
        "distillation": "string",
        "report_notebook_short_id": ""
      },
      "reader_summary": "string",
      "headline": "string",
      "next_steps": [
        "string"
      ],
      "iterations": [
        {
          "iteration_number": -2147483648,
          "status": "kept",
          "holdout_score": 0,
          "train_score": 0,
          "agent_description": "string",
          "summary": "string",
          "headline": "string",
          "model_spec": {
            "model_class": "sklearn.linear_model.LogisticRegression",
            "model_params": {
              "C": 1
            }
          }
        }
      ],
      "error": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

List all autoresearch training runs

List and retrieve training runs for a pipeline.

A training run records the agent's search for a model: each iteration's recipe and holdout score, and the summary of the run once it completes.

Required API key scopes

autoresearch:read

Path parameters

pipeline_id
string

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/training_runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/".format(
        project_id=project_id,
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
      "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
      "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
      "task_url": "string",
      "status": "pending",
      "kickoff_reason": "explore",
      "agent_runtime_adapter": "string",
      "agent_model": "string",
      "agent_model_label": "string",
      "agent_reasoning_effort": "string",
      "iteration_budget": -2147483648,
      "iteration_count": 0,
      "best_holdout_score": 0,
      "summary": {
        "target_event": "string",
        "horizon_days": 0,
        "best_holdout_score": 0,
        "champion_promoted": true,
        "champion_model_class": "string",
        "kept_ladder": [
          {
            "iteration_number": 0,
            "holdout_score": 0,
            "model_class": "string",
            "agent_description": "string"
          }
        ],
        "dead_ends": [
          {
            "iteration_number": 0,
            "holdout_score": 0,
            "model_class": "string",
            "agent_description": "string"
          }
        ],
        "recommended_next": "string",
        "distillation": "string",
        "report_notebook_short_id": ""
      },
      "reader_summary": "string",
      "headline": "string",
      "next_steps": [
        "string"
      ],
      "iterations": [
        {
          "iteration_number": -2147483648,
          "status": "kept",
          "holdout_score": 0,
          "train_score": 0,
          "agent_description": "string",
          "summary": "string",
          "headline": "string",
          "model_spec": {
            "model_class": "sklearn.linear_model.LogisticRegression",
            "model_params": {
              "C": 1
            }
          }
        }
      ],
      "error": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create autoresearch training runs

Open a new training run for a pipeline and return its id. An agent — the in-house sandbox, an external bring-your-own agent, or a scheduled job — then records iterations against this run and finalizes it with the complete endpoint. The run starts in 'running'.

Required API key scopes

autoresearch:write

Path parameters

pipeline_id
string

Request parameters

iteration_budget
integer

Response

Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/training_runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/\
	-d iteration_budget="integer"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/".format(
        project_id=project_id,
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"iteration_budget": "integer"
	}
).json()

Example response

Status 201 The opened training run. Record iterations against its id, then call complete.

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
  "task_url": "string",
  "status": "pending",
  "kickoff_reason": "explore",
  "agent_runtime_adapter": "string",
  "agent_model": "string",
  "agent_model_label": "string",
  "agent_reasoning_effort": "string",
  "iteration_budget": -2147483648,
  "iteration_count": 0,
  "best_holdout_score": 0,
  "summary": {
    "target_event": "string",
    "horizon_days": 0,
    "best_holdout_score": 0,
    "champion_promoted": true,
    "champion_model_class": "string",
    "kept_ladder": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "dead_ends": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "recommended_next": "string",
    "distillation": "string",
    "report_notebook_short_id": ""
  },
  "reader_summary": "string",
  "headline": "string",
  "next_steps": [
    "string"
  ],
  "iterations": [
    {
      "iteration_number": -2147483648,
      "status": "kept",
      "holdout_score": 0,
      "train_score": 0,
      "agent_description": "string",
      "summary": "string",
      "headline": "string",
      "model_spec": {
        "model_class": "sklearn.linear_model.LogisticRegression",
        "model_params": {
          "C": 1
        }
      }
    }
  ],
  "error": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Status 400 The pipeline is archived or paused, a run is already in progress, or an action target needs the action:read scope.

Create autoresearch training runs

Required API key scopes

autoresearch:write

Path parameters

pipeline_id
string

Request parameters

iteration_budget
integer

Response

Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/training_runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/\
	-d iteration_budget="integer"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/".format(
        project_id=project_id,
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"iteration_budget": "integer"
	}
).json()

Example response

Status 201 The opened training run. Record iterations against its id, then call complete.

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
  "task_url": "string",
  "status": "pending",
  "kickoff_reason": "explore",
  "agent_runtime_adapter": "string",
  "agent_model": "string",
  "agent_model_label": "string",
  "agent_reasoning_effort": "string",
  "iteration_budget": -2147483648,
  "iteration_count": 0,
  "best_holdout_score": 0,
  "summary": {
    "target_event": "string",
    "horizon_days": 0,
    "best_holdout_score": 0,
    "champion_promoted": true,
    "champion_model_class": "string",
    "kept_ladder": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "dead_ends": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "recommended_next": "string",
    "distillation": "string",
    "report_notebook_short_id": ""
  },
  "reader_summary": "string",
  "headline": "string",
  "next_steps": [
    "string"
  ],
  "iterations": [
    {
      "iteration_number": -2147483648,
      "status": "kept",
      "holdout_score": 0,
      "train_score": 0,
      "agent_description": "string",
      "summary": "string",
      "headline": "string",
      "model_spec": {
        "model_class": "sklearn.linear_model.LogisticRegression",
        "model_params": {
          "C": 1
        }
      }
    }
  ],
  "error": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Status 400 The pipeline is archived or paused, a run is already in progress, or an action target needs the action:read scope.

Retrieve autoresearch training runs

List and retrieve training runs for a pipeline.

A training run records the agent's search for a model: each iteration's recipe and holdout score, and the summary of the run once it completes.

Required API key scopes

autoresearch:read

Path parameters

id
string
pipeline_id
string

Response

Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
  "task_url": "string",
  "status": "pending",
  "kickoff_reason": "explore",
  "agent_runtime_adapter": "string",
  "agent_model": "string",
  "agent_model_label": "string",
  "agent_reasoning_effort": "string",
  "iteration_budget": -2147483648,
  "iteration_count": 0,
  "best_holdout_score": 0,
  "summary": {
    "target_event": "string",
    "horizon_days": 0,
    "best_holdout_score": 0,
    "champion_promoted": true,
    "champion_model_class": "string",
    "kept_ladder": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "dead_ends": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "recommended_next": "string",
    "distillation": "string",
    "report_notebook_short_id": ""
  },
  "reader_summary": "string",
  "headline": "string",
  "next_steps": [
    "string"
  ],
  "iterations": [
    {
      "iteration_number": -2147483648,
      "status": "kept",
      "holdout_score": 0,
      "train_score": 0,
      "agent_description": "string",
      "summary": "string",
      "headline": "string",
      "model_spec": {
        "model_class": "sklearn.linear_model.LogisticRegression",
        "model_params": {
          "C": 1
        }
      }
    }
  ],
  "error": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Retrieve autoresearch training runs

List and retrieve training runs for a pipeline.

A training run records the agent's search for a model: each iteration's recipe and holdout score, and the summary of the run once it completes.

Required API key scopes

autoresearch:read

Path parameters

id
string
pipeline_id
string

Response

Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
  "task_url": "string",
  "status": "pending",
  "kickoff_reason": "explore",
  "agent_runtime_adapter": "string",
  "agent_model": "string",
  "agent_model_label": "string",
  "agent_reasoning_effort": "string",
  "iteration_budget": -2147483648,
  "iteration_count": 0,
  "best_holdout_score": 0,
  "summary": {
    "target_event": "string",
    "horizon_days": 0,
    "best_holdout_score": 0,
    "champion_promoted": true,
    "champion_model_class": "string",
    "kept_ladder": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "dead_ends": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "recommended_next": "string",
    "distillation": "string",
    "report_notebook_short_id": ""
  },
  "reader_summary": "string",
  "headline": "string",
  "next_steps": [
    "string"
  ],
  "iterations": [
    {
      "iteration_number": -2147483648,
      "status": "kept",
      "holdout_score": 0,
      "train_score": 0,
      "agent_description": "string",
      "summary": "string",
      "headline": "string",
      "model_spec": {
        "model_class": "sklearn.linear_model.LogisticRegression",
        "model_params": {
          "C": 1
        }
      }
    }
  ],
  "error": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Retrieve autoresearch training runs artifacts

List the files an agent has uploaded for this training run's artifact bundle (train.py, predict.py, features.sql, and any eda/ notebooks).

Required API key scopes

autoresearch:read

Path parameters

id
string
pipeline_id
string

Response

Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/artifacts/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 The relative paths of every file in this run's artifact bundle.

RESPONSE
{
  "paths": [
    "string"
  ],
  "count": 0
}

Retrieve autoresearch training runs artifacts

List the files an agent has uploaded for this training run's artifact bundle (train.py, predict.py, features.sql, and any eda/ notebooks).

Required API key scopes

autoresearch:read

Path parameters

id
string
pipeline_id
string

Response

Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/artifacts/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 The relative paths of every file in this run's artifact bundle.

RESPONSE
{
  "paths": [
    "string"
  ],
  "count": 0
}

Create autoresearch training runs artifacts delete

Remove one file from this training run's artifact bundle. Idempotent — deleting a missing file is a no-op. The bundle is frozen once the run completes or fails.

Required API key scopes

autoresearch:write

Path parameters

id
string
pipeline_id
string

Request parameters

path
string

Response

Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts/delete
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts/delete/\
	-d path="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/artifacts/delete/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"path": "string"
	}
).json()

Example response

Status 200 Whether a file existed at that path and was removed.

RESPONSE
{
  "path": "string",
  "deleted": true
}

Status 400 Invalid path, or the run is no longer running.

Status 503 Object storage is unavailable; nothing was deleted.

Create autoresearch training runs artifacts delete

Remove one file from this training run's artifact bundle. Idempotent — deleting a missing file is a no-op. The bundle is frozen once the run completes or fails.

Required API key scopes

autoresearch:write

Path parameters

id
string
pipeline_id
string

Request parameters

path
string

Response

Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts/delete
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts/delete/\
	-d path="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/artifacts/delete/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"path": "string"
	}
).json()

Example response

Status 200 Whether a file existed at that path and was removed.

RESPONSE
{
  "path": "string",
  "deleted": true
}

Status 400 Invalid path, or the run is no longer running.

Status 503 Object storage is unavailable; nothing was deleted.

Create autoresearch training runs artifacts get

Fetch one file from this training run's artifact bundle, base64-encoded.

Required API key scopes

autoresearch:read

Path parameters

id
string
pipeline_id
string

Request parameters

path
string

Response

Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts/get
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts/get/\
	-d path="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/artifacts/get/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"path": "string"
	}
).json()

Example response

Status 200 The file's content, base64-encoded, with its size and hash.

RESPONSE
{
  "path": "string",
  "size_bytes": 0,
  "sha256": "string",
  "content_base64": "string"
}

Status 404 No file at that path in this run's bundle.

Create autoresearch training runs artifacts get

Fetch one file from this training run's artifact bundle, base64-encoded.

Required API key scopes

autoresearch:read

Path parameters

id
string
pipeline_id
string

Request parameters

path
string

Response

Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts/get
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts/get/\
	-d path="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/artifacts/get/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"path": "string"
	}
).json()

Example response

Status 200 The file's content, base64-encoded, with its size and hash.

RESPONSE
{
  "path": "string",
  "size_bytes": 0,
  "sha256": "string",
  "content_base64": "string"
}

Status 404 No file at that path in this run's bundle.

Create autoresearch training runs artifacts upload

Upload one file of this training run's artifact bundle. Send the file contents base64-encoded in content_base64. Re-uploading the same path overwrites it. Use this — not curl/set_output — to author train.py, predict.py, and features.sql. The bundle is frozen once the run completes or fails.

Required API key scopes

autoresearch:write

Path parameters

id
string
pipeline_id
string

Request parameters

path
string
content_base64
string

Response

Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts/upload
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts/upload/\
	-d path="string",\
	-d content_base64="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/artifacts/upload/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"path": "string",
		"content_base64": "string"
	}
).json()

Example response

Status 201 The stored file's path, size, and content hash.

RESPONSE
{
  "path": "string",
  "size_bytes": 0,
  "sha256": "string"
}

Status 400 Invalid or reserved path, content is not base64, file exceeds the size limit, the bundle holds its maximum number of files, or the run is no longer running.

Status 503 Object storage is unavailable; nothing was stored.

Create autoresearch training runs artifacts upload

Required API key scopes

autoresearch:write

Path parameters

id
string
pipeline_id
string

Request parameters

path
string
content_base64
string

Response

Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts/upload
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/artifacts/upload/\
	-d path="string",\
	-d content_base64="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/artifacts/upload/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"path": "string",
		"content_base64": "string"
	}
).json()

Example response

Status 201 The stored file's path, size, and content hash.

RESPONSE
{
  "path": "string",
  "size_bytes": 0,
  "sha256": "string"
}

Status 400 Invalid or reserved path, content is not base64, file exceeds the size limit, the bundle holds its maximum number of files, or the run is no longer running.

Status 503 Object storage is unavailable; nothing was stored.

Create autoresearch training runs complete

Finalize a training run. The backend selects the kept iteration with the highest holdout score, decides champion vs challenger via the promotion ladder, and persists the model. best_iteration_id is advisory: it breaks a tie at the top score and is otherwise logged and ignored. Agents cannot set the champion directly, because promotion is server-side.

Required API key scopes

autoresearch:write

Path parameters

id
string
pipeline_id
string

Request parameters

best_iteration_id
string | null
model_explanation
recommended_next
string
Default:
distillation
string
Default:
reader_summary
string | null
headline
string | null
next_steps
array | null
report_notebook_short_id
string
Default:

Response

Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/complete
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/complete/\
	-d best_iteration_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/complete/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"best_iteration_id": "string"
	}
).json()

Example response

Status 200 The completed training run. Call autoresearch-models-list to see the resulting champion/challenger.

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
  "task_url": "string",
  "status": "pending",
  "kickoff_reason": "explore",
  "agent_runtime_adapter": "string",
  "agent_model": "string",
  "agent_model_label": "string",
  "agent_reasoning_effort": "string",
  "iteration_budget": -2147483648,
  "iteration_count": 0,
  "best_holdout_score": 0,
  "summary": {
    "target_event": "string",
    "horizon_days": 0,
    "best_holdout_score": 0,
    "champion_promoted": true,
    "champion_model_class": "string",
    "kept_ladder": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "dead_ends": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "recommended_next": "string",
    "distillation": "string",
    "report_notebook_short_id": ""
  },
  "reader_summary": "string",
  "headline": "string",
  "next_steps": [
    "string"
  ],
  "iterations": [
    {
      "iteration_number": -2147483648,
      "status": "kept",
      "holdout_score": 0,
      "train_score": 0,
      "agent_description": "string",
      "summary": "string",
      "headline": "string",
      "model_spec": {
        "model_class": "sklearn.linear_model.LogisticRegression",
        "model_params": {
          "C": 1
        }
      }
    }
  ],
  "error": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Status 400 Run is already completed or failed, has no recorded iterations, or has no usable model artifact (no bundle and no feature SQL).

Create autoresearch training runs complete

Required API key scopes

autoresearch:write

Path parameters

id
string
pipeline_id
string

Request parameters

best_iteration_id
string | null
model_explanation
recommended_next
string
Default:
distillation
string
Default:
reader_summary
string | null
headline
string | null
next_steps
array | null
report_notebook_short_id
string
Default:

Response

Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/complete
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/complete/\
	-d best_iteration_id="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/complete/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"best_iteration_id": "string"
	}
).json()

Example response

Status 200 The completed training run. Call autoresearch-models-list to see the resulting champion/challenger.

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
  "task_url": "string",
  "status": "pending",
  "kickoff_reason": "explore",
  "agent_runtime_adapter": "string",
  "agent_model": "string",
  "agent_model_label": "string",
  "agent_reasoning_effort": "string",
  "iteration_budget": -2147483648,
  "iteration_count": 0,
  "best_holdout_score": 0,
  "summary": {
    "target_event": "string",
    "horizon_days": 0,
    "best_holdout_score": 0,
    "champion_promoted": true,
    "champion_model_class": "string",
    "kept_ladder": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "dead_ends": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "recommended_next": "string",
    "distillation": "string",
    "report_notebook_short_id": ""
  },
  "reader_summary": "string",
  "headline": "string",
  "next_steps": [
    "string"
  ],
  "iterations": [
    {
      "iteration_number": -2147483648,
      "status": "kept",
      "holdout_score": 0,
      "train_score": 0,
      "agent_description": "string",
      "summary": "string",
      "headline": "string",
      "model_spec": {
        "model_class": "sklearn.linear_model.LogisticRegression",
        "model_params": {
          "C": 1
        }
      }
    }
  ],
  "error": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Status 400 Run is already completed or failed, has no recorded iterations, or has no usable model artifact (no bundle and no feature SQL).

Create autoresearch training runs iterations

Record one iteration of an open training run. Idempotent on iteration_number: re-sending the same number updates that iteration. A new iteration_number is refused once the run's iteration_budget is used. The recipe is validated server-side: feature_sql must be a read-only SELECT from {anchors} keyed on person_id, and model_class must be set. The class allowlist applies only at completion, to a run that uploaded no bundle.

Required API key scopes

autoresearch:write

Path parameters

id
string
pipeline_id
string

Request parameters

iteration_number
integer
recipe_snapshot
object
model_spec
object
status
train_score
number | null
holdout_score
number | null
agent_description
string
Default:
summary
string | null
headline
string | null
agent_confidence
number | null
parent_suggestion
string | null

Response

Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/iterations
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/iterations/\
	-d iteration_number="integer",\
	-d recipe_snapshot={"feature_sql":"SELECT a.person_id AS distinct_id, countIf(e.event = '$pageview') AS pageviews FROM {anchors} a LEFT JOIN events e ON e.person_id = a.person_id AND e.timestamp < a.cutoff_ts GROUP BY a.person_id, a.cutoff_ts","feature_transforms":[]},\
	-d model_spec={"model_class":"sklearn.linear_model.LogisticRegression","model_params":{"C":1}},\
	-d status=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/iterations/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"iteration_number": "integer",
		"recipe_snapshot": {
			"feature_sql": "SELECT a.person_id AS distinct_id, countIf(e.event = '$pageview') AS pageviews FROM {anchors} a LEFT JOIN events e ON e.person_id = a.person_id AND e.timestamp < a.cutoff_ts GROUP BY a.person_id, a.cutoff_ts",
			"feature_transforms": []
		},
		"model_spec": {
			"model_class": "sklearn.linear_model.LogisticRegression",
			"model_params": {
				"C": 1
			}
		}
	}
).json()

Example response

Status 201 The recorded iteration.

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "training_run": "b0582a6a-afc4-4596-8956-6a738bec6f9e",
  "iteration_number": -2147483648,
  "recipe_hash": "string",
  "recipe_snapshot": {
    "feature_sql": "SELECT a.person_id AS distinct_id, countIf(e.event = '$pageview') AS pageviews FROM {anchors} a LEFT JOIN events e ON e.person_id = a.person_id AND e.timestamp < a.cutoff_ts GROUP BY a.person_id, a.cutoff_ts",
    "feature_transforms": []
  },
  "model_spec": {
    "model_class": "sklearn.linear_model.LogisticRegression",
    "model_params": {
      "C": 1
    }
  },
  "train_score": 0,
  "holdout_score": 0,
  "status": "kept",
  "agent_description": "string",
  "summary": "string",
  "headline": "string",
  "agent_confidence": 0,
  "parent_suggestion": "4e59bd53-dd8b-4b8a-9e67-6cf268d45bee",
  "created_at": "2019-08-24T14:15:22Z"
}

Status 400 Recipe failed validation (feature_sql does not read from {anchors}, model_class missing, a non-object model_params), the run is not running, or its iteration budget is used.

Create autoresearch training runs iterations

Required API key scopes

autoresearch:write

Path parameters

id
string
pipeline_id
string

Request parameters

iteration_number
integer
recipe_snapshot
object
model_spec
object
status
train_score
number | null
holdout_score
number | null
agent_description
string
Default:
summary
string | null
headline
string | null
agent_confidence
number | null
parent_suggestion
string | null

Response

Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/iterations
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/iterations/\
	-d iteration_number="integer",\
	-d recipe_snapshot={"feature_sql":"SELECT a.person_id AS distinct_id, countIf(e.event = '$pageview') AS pageviews FROM {anchors} a LEFT JOIN events e ON e.person_id = a.person_id AND e.timestamp < a.cutoff_ts GROUP BY a.person_id, a.cutoff_ts","feature_transforms":[]},\
	-d model_spec={"model_class":"sklearn.linear_model.LogisticRegression","model_params":{"C":1}},\
	-d status=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/iterations/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"iteration_number": "integer",
		"recipe_snapshot": {
			"feature_sql": "SELECT a.person_id AS distinct_id, countIf(e.event = '$pageview') AS pageviews FROM {anchors} a LEFT JOIN events e ON e.person_id = a.person_id AND e.timestamp < a.cutoff_ts GROUP BY a.person_id, a.cutoff_ts",
			"feature_transforms": []
		},
		"model_spec": {
			"model_class": "sklearn.linear_model.LogisticRegression",
			"model_params": {
				"C": 1
			}
		}
	}
).json()

Example response

Status 201 The recorded iteration.

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "training_run": "b0582a6a-afc4-4596-8956-6a738bec6f9e",
  "iteration_number": -2147483648,
  "recipe_hash": "string",
  "recipe_snapshot": {
    "feature_sql": "SELECT a.person_id AS distinct_id, countIf(e.event = '$pageview') AS pageviews FROM {anchors} a LEFT JOIN events e ON e.person_id = a.person_id AND e.timestamp < a.cutoff_ts GROUP BY a.person_id, a.cutoff_ts",
    "feature_transforms": []
  },
  "model_spec": {
    "model_class": "sklearn.linear_model.LogisticRegression",
    "model_params": {
      "C": 1
    }
  },
  "train_score": 0,
  "holdout_score": 0,
  "status": "kept",
  "agent_description": "string",
  "summary": "string",
  "headline": "string",
  "agent_confidence": 0,
  "parent_suggestion": "4e59bd53-dd8b-4b8a-9e67-6cf268d45bee",
  "created_at": "2019-08-24T14:15:22Z"
}

Status 400 Recipe failed validation (feature_sql does not read from {anchors}, model_class missing, a non-object model_params), the run is not running, or its iteration budget is used.

Create autoresearch training runs materialize features

Run features_sql server-side against the labeled training population and write the resulting train/holdout feature and label parquet files directly into this run's sandbox. Returns the local sandbox paths, row counts, and feature columns. The rows never pass through the agent's context and there is no 500-row cap. Read the returned paths with pd.read_parquet and iterate in Python.

Required API key scopes

autoresearch:writequery:read

Path parameters

id
string
pipeline_id
string

Request parameters

features_sql
string

Response

Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/materialize-features
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/materialize-features/\
	-d features_sql="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/materialize-features/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"features_sql": "string"
	}
).json()

Example response

Status 200 Sandbox paths to the train/holdout feature and label parquet files, plus row counts and feature columns.

RESPONSE
{
  "train_features_path": "string",
  "train_labels_path": "string",
  "holdout_features_path": "string",
  "holdout_labels_path": "string",
  "n_train": 0,
  "n_holdout": 0,
  "n_features": 0,
  "feature_cols": [
    "string"
  ],
  "elapsed_s": 0.1,
  "rows_read": 0,
  "hints": [
    "string"
  ]
}

Status 400 Run not running, features_sql invalid, sandbox unavailable, the query produced no usable rows, or the holdout split cannot be scored.

Create autoresearch training runs materialize features

Required API key scopes

autoresearch:writequery:read

Path parameters

id
string
pipeline_id
string

Request parameters

features_sql
string

Response

Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/materialize-features
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/training_runs/:id/materialize-features/\
	-d features_sql="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/autoresearch/{pipeline_id}/training_runs/{autoresearch-2_id}/materialize-features/".format(
        project_id=project_id,
		autoresearch-2_id="<the autoresearch-2 id>",
		pipeline_id="<the pipeline id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"features_sql": "string"
	}
).json()

Example response

Status 200 Sandbox paths to the train/holdout feature and label parquet files, plus row counts and feature columns.

RESPONSE
{
  "train_features_path": "string",
  "train_labels_path": "string",
  "holdout_features_path": "string",
  "holdout_labels_path": "string",
  "n_train": 0,
  "n_holdout": 0,
  "n_features": 0,
  "feature_cols": [
    "string"
  ],
  "elapsed_s": 0.1,
  "rows_read": 0,
  "hints": [
    "string"
  ]
}

Status 400 Run not running, features_sql invalid, sandbox unavailable, the query produced no usable rows, or the holdout split cannot be scored.

← Previous pageNext page →