Loops

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

Endpoints

`GET`
`POST`
`GET`
`PATCH`
`DELETE`
`POST`
`POST`
`GET`
`POST`

List all loops

List loops visible to the caller: personal loops they own, plus every team loop. The response also carries max_loops_per_team and total_loop_count so a client can show remaining capacity and disable creation at the cap without hardcoding the limit.

Required API key scopes

loop:read

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/loops
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/loops/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/loops/".format(
        project_id=project_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",
      "team_id": 0,
      "created_by_id": 0,
      "name": "string",
      "description": "string",
      "visibility": "string",
      "instructions": "string",
      "runtime_adapter": "string",
      "model": "string",
      "reasoning_effort": "string",
      "repositories": [
        {
          "github_integration_id": 0,
          "full_name": "string"
        }
      ],
      "sandbox_environment_id": "1c0606a3-c229-47ab-8e7a-30e01efeba88",
      "enabled": true,
      "disabled_reason": "string",
      "overlap_policy": "string",
      "behaviors": {
        "create_prs": true,
        "watch_ci": true,
        "fix_review_comments": true,
        "max_fix_iterations": 0
      },
      "connectors": {
        "mcp_installation_ids": [
          "string"
        ],
        "posthog_mcp_scopes": "string"
      },
      "notifications": {
        "push": {
          "enabled": true,
          "events": [
            "string"
          ],
          "params": {}
        },
        "email": {
          "enabled": true,
          "events": [
            "string"
          ],
          "params": {}
        },
        "slack": {
          "enabled": true,
          "events": [
            "string"
          ],
          "params": {}
        }
      },
      "context_target": {
        "outputs": {
          "post_to_feed": true,
          "update_context": true,
          "canvas_id": "string"
        },
        "channel_id": "string",
        "name": "string"
      },
      "internal": true,
      "origin_product": "string",
      "last_run_at": "2019-08-24T14:15:22Z",
      "last_run_status": "string",
      "last_error": "string",
      "consecutive_failures": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "triggers": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "loop_id": "48f92213-f7f6-4842-bbaf-7104e15dc651",
          "type": "string",
          "enabled": true,
          "config": {},
          "schedule_sync_status": "string",
          "last_fired_at": "2019-08-24T14:15:22Z",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z"
        }
      ],
      "skill_bundles": [
        {
          "id": "string",
          "skill_name": "string",
          "skill_source": "string",
          "size": 0,
          "content_sha256": "string",
          "uploaded_at": "string"
        }
      ]
    }
  ],
  "max_loops_per_team": 0,
  "total_loop_count": 0
}

List all loops

Required API key scopes

loop:read

Query parameters

limit
integer
offset
integer

Response

Example request

GET /api/projects/:project_id/loops
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/loops/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/loops/".format(
        project_id=project_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",
      "team_id": 0,
      "created_by_id": 0,
      "name": "string",
      "description": "string",
      "visibility": "string",
      "instructions": "string",
      "runtime_adapter": "string",
      "model": "string",
      "reasoning_effort": "string",
      "repositories": [
        {
          "github_integration_id": 0,
          "full_name": "string"
        }
      ],
      "sandbox_environment_id": "1c0606a3-c229-47ab-8e7a-30e01efeba88",
      "enabled": true,
      "disabled_reason": "string",
      "overlap_policy": "string",
      "behaviors": {
        "create_prs": true,
        "watch_ci": true,
        "fix_review_comments": true,
        "max_fix_iterations": 0
      },
      "connectors": {
        "mcp_installation_ids": [
          "string"
        ],
        "posthog_mcp_scopes": "string"
      },
      "notifications": {
        "push": {
          "enabled": true,
          "events": [
            "string"
          ],
          "params": {}
        },
        "email": {
          "enabled": true,
          "events": [
            "string"
          ],
          "params": {}
        },
        "slack": {
          "enabled": true,
          "events": [
            "string"
          ],
          "params": {}
        }
      },
      "context_target": {
        "outputs": {
          "post_to_feed": true,
          "update_context": true,
          "canvas_id": "string"
        },
        "channel_id": "string",
        "name": "string"
      },
      "internal": true,
      "origin_product": "string",
      "last_run_at": "2019-08-24T14:15:22Z",
      "last_run_status": "string",
      "last_error": "string",
      "consecutive_failures": 0,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "triggers": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "loop_id": "48f92213-f7f6-4842-bbaf-7104e15dc651",
          "type": "string",
          "enabled": true,
          "config": {},
          "schedule_sync_status": "string",
          "last_fired_at": "2019-08-24T14:15:22Z",
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z"
        }
      ],
      "skill_bundles": [
        {
          "id": "string",
          "skill_name": "string",
          "skill_source": "string",
          "size": 0,
          "content_sha256": "string",
          "uploaded_at": "string"
        }
      ]
    }
  ],
  "max_loops_per_team": 0,
  "total_loop_count": 0
}

Create loops

API for managing loops — named, cloud-executed agent automations triggered by schedule, GitHub events or authenticated API calls. See products/tasks/docs/LOOPS.md.

Required API key scopes

loop:write

Request parameters

name
string
description
string
Default:
take_ownership
boolean
Default: false
visibility
Default: personal
instructions
string
runtime_adapter
model
string
Default:
reasoning_effort
repositories
array
sandbox_environment
string | null
enabled
boolean
Default: true
overlap_policy
Default: skip
behaviors
connectors
notifications
context_target
triggers
array

Response

Example request

POST /api/projects/:project_id/loops
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/loops/\
	-d name="string",\
	-d instructions="string",\
	-d runtime_adapter=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/loops/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string",
		"instructions": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "created_by_id": 0,
  "name": "string",
  "description": "string",
  "visibility": "string",
  "instructions": "string",
  "runtime_adapter": "string",
  "model": "string",
  "reasoning_effort": "string",
  "repositories": [
    {
      "github_integration_id": 0,
      "full_name": "string"
    }
  ],
  "sandbox_environment_id": "1c0606a3-c229-47ab-8e7a-30e01efeba88",
  "enabled": true,
  "disabled_reason": "string",
  "overlap_policy": "string",
  "behaviors": {
    "create_prs": true,
    "watch_ci": true,
    "fix_review_comments": true,
    "max_fix_iterations": 0
  },
  "connectors": {
    "mcp_installation_ids": [
      "string"
    ],
    "posthog_mcp_scopes": "string"
  },
  "notifications": {
    "push": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    },
    "email": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    },
    "slack": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    }
  },
  "context_target": {
    "outputs": {
      "post_to_feed": true,
      "update_context": true,
      "canvas_id": "string"
    },
    "channel_id": "string",
    "name": "string"
  },
  "internal": true,
  "origin_product": "string",
  "last_run_at": "2019-08-24T14:15:22Z",
  "last_run_status": "string",
  "last_error": "string",
  "consecutive_failures": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "triggers": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "loop_id": "48f92213-f7f6-4842-bbaf-7104e15dc651",
      "type": "string",
      "enabled": true,
      "config": {},
      "schedule_sync_status": "string",
      "last_fired_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "skill_bundles": [
    {
      "id": "string",
      "skill_name": "string",
      "skill_source": "string",
      "size": 0,
      "content_sha256": "string",
      "uploaded_at": "string"
    }
  ]
}

Status 429 A per-team loop or per-loop trigger safety limit was reached

Create loops

API for managing loops — named, cloud-executed agent automations triggered by schedule, GitHub events or authenticated API calls. See products/tasks/docs/LOOPS.md.

Required API key scopes

loop:write

Request parameters

name
string
description
string
Default:
take_ownership
boolean
Default: false
visibility
Default: personal
instructions
string
runtime_adapter
model
string
Default:
reasoning_effort
repositories
array
sandbox_environment
string | null
enabled
boolean
Default: true
overlap_policy
Default: skip
behaviors
connectors
notifications
context_target
triggers
array

Response

Example request

POST /api/projects/:project_id/loops
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/loops/\
	-d name="string",\
	-d instructions="string",\
	-d runtime_adapter=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/loops/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string",
		"instructions": "string"
	}
).json()

Example response

Status 201

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "created_by_id": 0,
  "name": "string",
  "description": "string",
  "visibility": "string",
  "instructions": "string",
  "runtime_adapter": "string",
  "model": "string",
  "reasoning_effort": "string",
  "repositories": [
    {
      "github_integration_id": 0,
      "full_name": "string"
    }
  ],
  "sandbox_environment_id": "1c0606a3-c229-47ab-8e7a-30e01efeba88",
  "enabled": true,
  "disabled_reason": "string",
  "overlap_policy": "string",
  "behaviors": {
    "create_prs": true,
    "watch_ci": true,
    "fix_review_comments": true,
    "max_fix_iterations": 0
  },
  "connectors": {
    "mcp_installation_ids": [
      "string"
    ],
    "posthog_mcp_scopes": "string"
  },
  "notifications": {
    "push": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    },
    "email": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    },
    "slack": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    }
  },
  "context_target": {
    "outputs": {
      "post_to_feed": true,
      "update_context": true,
      "canvas_id": "string"
    },
    "channel_id": "string",
    "name": "string"
  },
  "internal": true,
  "origin_product": "string",
  "last_run_at": "2019-08-24T14:15:22Z",
  "last_run_status": "string",
  "last_error": "string",
  "consecutive_failures": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "triggers": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "loop_id": "48f92213-f7f6-4842-bbaf-7104e15dc651",
      "type": "string",
      "enabled": true,
      "config": {},
      "schedule_sync_status": "string",
      "last_fired_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "skill_bundles": [
    {
      "id": "string",
      "skill_name": "string",
      "skill_source": "string",
      "size": 0,
      "content_sha256": "string",
      "uploaded_at": "string"
    }
  ]
}

Status 429 A per-team loop or per-loop trigger safety limit was reached

Retrieve loops

API for managing loops — named, cloud-executed agent automations triggered by schedule, GitHub events or authenticated API calls. See products/tasks/docs/LOOPS.md.

Required API key scopes

loop:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/loops/: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/loops/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/loops/{loop_id}/".format(
        project_id=project_id,
		loop_id="<the loop id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "created_by_id": 0,
  "name": "string",
  "description": "string",
  "visibility": "string",
  "instructions": "string",
  "runtime_adapter": "string",
  "model": "string",
  "reasoning_effort": "string",
  "repositories": [
    {
      "github_integration_id": 0,
      "full_name": "string"
    }
  ],
  "sandbox_environment_id": "1c0606a3-c229-47ab-8e7a-30e01efeba88",
  "enabled": true,
  "disabled_reason": "string",
  "overlap_policy": "string",
  "behaviors": {
    "create_prs": true,
    "watch_ci": true,
    "fix_review_comments": true,
    "max_fix_iterations": 0
  },
  "connectors": {
    "mcp_installation_ids": [
      "string"
    ],
    "posthog_mcp_scopes": "string"
  },
  "notifications": {
    "push": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    },
    "email": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    },
    "slack": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    }
  },
  "context_target": {
    "outputs": {
      "post_to_feed": true,
      "update_context": true,
      "canvas_id": "string"
    },
    "channel_id": "string",
    "name": "string"
  },
  "internal": true,
  "origin_product": "string",
  "last_run_at": "2019-08-24T14:15:22Z",
  "last_run_status": "string",
  "last_error": "string",
  "consecutive_failures": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "triggers": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "loop_id": "48f92213-f7f6-4842-bbaf-7104e15dc651",
      "type": "string",
      "enabled": true,
      "config": {},
      "schedule_sync_status": "string",
      "last_fired_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "skill_bundles": [
    {
      "id": "string",
      "skill_name": "string",
      "skill_source": "string",
      "size": 0,
      "content_sha256": "string",
      "uploaded_at": "string"
    }
  ]
}

Status 404 Loop not found

Retrieve loops

API for managing loops — named, cloud-executed agent automations triggered by schedule, GitHub events or authenticated API calls. See products/tasks/docs/LOOPS.md.

Required API key scopes

loop:read

Path parameters

id
string

Response

Example request

GET /api/projects/:project_id/loops/: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/loops/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/loops/{loop_id}/".format(
        project_id=project_id,
		loop_id="<the loop id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "created_by_id": 0,
  "name": "string",
  "description": "string",
  "visibility": "string",
  "instructions": "string",
  "runtime_adapter": "string",
  "model": "string",
  "reasoning_effort": "string",
  "repositories": [
    {
      "github_integration_id": 0,
      "full_name": "string"
    }
  ],
  "sandbox_environment_id": "1c0606a3-c229-47ab-8e7a-30e01efeba88",
  "enabled": true,
  "disabled_reason": "string",
  "overlap_policy": "string",
  "behaviors": {
    "create_prs": true,
    "watch_ci": true,
    "fix_review_comments": true,
    "max_fix_iterations": 0
  },
  "connectors": {
    "mcp_installation_ids": [
      "string"
    ],
    "posthog_mcp_scopes": "string"
  },
  "notifications": {
    "push": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    },
    "email": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    },
    "slack": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    }
  },
  "context_target": {
    "outputs": {
      "post_to_feed": true,
      "update_context": true,
      "canvas_id": "string"
    },
    "channel_id": "string",
    "name": "string"
  },
  "internal": true,
  "origin_product": "string",
  "last_run_at": "2019-08-24T14:15:22Z",
  "last_run_status": "string",
  "last_error": "string",
  "consecutive_failures": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "triggers": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "loop_id": "48f92213-f7f6-4842-bbaf-7104e15dc651",
      "type": "string",
      "enabled": true,
      "config": {},
      "schedule_sync_status": "string",
      "last_fired_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "skill_bundles": [
    {
      "id": "string",
      "skill_name": "string",
      "skill_source": "string",
      "size": 0,
      "content_sha256": "string",
      "uploaded_at": "string"
    }
  ]
}

Status 404 Loop not found

Update loops

Partial update. Identity-bearing fields (instructions, repositories, connectors, behaviors, model config, triggers) are owner-only on team loops; name, description, notifications and enable/pause are editable by any team member.

Required API key scopes

loop:write

Path parameters

id
string

Request parameters

name
string
description
string
Default:
take_ownership
boolean
Default: false
visibility
Default: personal
instructions
string
runtime_adapter
model
string
Default:
reasoning_effort
repositories
array
sandbox_environment
string | null
enabled
boolean
Default: true
overlap_policy
Default: skip
behaviors
connectors
notifications
context_target
triggers
array

Response

Example request

PATCH /api/projects/:project_id/loops/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/loops/:id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/loops/{loop_id}/".format(
        project_id=project_id,
		loop_id="<the loop id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "created_by_id": 0,
  "name": "string",
  "description": "string",
  "visibility": "string",
  "instructions": "string",
  "runtime_adapter": "string",
  "model": "string",
  "reasoning_effort": "string",
  "repositories": [
    {
      "github_integration_id": 0,
      "full_name": "string"
    }
  ],
  "sandbox_environment_id": "1c0606a3-c229-47ab-8e7a-30e01efeba88",
  "enabled": true,
  "disabled_reason": "string",
  "overlap_policy": "string",
  "behaviors": {
    "create_prs": true,
    "watch_ci": true,
    "fix_review_comments": true,
    "max_fix_iterations": 0
  },
  "connectors": {
    "mcp_installation_ids": [
      "string"
    ],
    "posthog_mcp_scopes": "string"
  },
  "notifications": {
    "push": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    },
    "email": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    },
    "slack": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    }
  },
  "context_target": {
    "outputs": {
      "post_to_feed": true,
      "update_context": true,
      "canvas_id": "string"
    },
    "channel_id": "string",
    "name": "string"
  },
  "internal": true,
  "origin_product": "string",
  "last_run_at": "2019-08-24T14:15:22Z",
  "last_run_status": "string",
  "last_error": "string",
  "consecutive_failures": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "triggers": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "loop_id": "48f92213-f7f6-4842-bbaf-7104e15dc651",
      "type": "string",
      "enabled": true,
      "config": {},
      "schedule_sync_status": "string",
      "last_fired_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "skill_bundles": [
    {
      "id": "string",
      "skill_name": "string",
      "skill_source": "string",
      "size": 0,
      "content_sha256": "string",
      "uploaded_at": "string"
    }
  ]
}

Status 403 Not permitted to change these fields

Status 404 Loop not found

Status 429 A per-loop trigger safety limit was reached

Update loops

Required API key scopes

loop:write

Path parameters

id
string

Request parameters

name
string
description
string
Default:
take_ownership
boolean
Default: false
visibility
Default: personal
instructions
string
runtime_adapter
model
string
Default:
reasoning_effort
repositories
array
sandbox_environment
string | null
enabled
boolean
Default: true
overlap_policy
Default: skip
behaviors
connectors
notifications
context_target
triggers
array

Response

Example request

PATCH /api/projects/:project_id/loops/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/loops/:id/\
	-d name="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/loops/{loop_id}/".format(
        project_id=project_id,
		loop_id="<the loop id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"name": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "team_id": 0,
  "created_by_id": 0,
  "name": "string",
  "description": "string",
  "visibility": "string",
  "instructions": "string",
  "runtime_adapter": "string",
  "model": "string",
  "reasoning_effort": "string",
  "repositories": [
    {
      "github_integration_id": 0,
      "full_name": "string"
    }
  ],
  "sandbox_environment_id": "1c0606a3-c229-47ab-8e7a-30e01efeba88",
  "enabled": true,
  "disabled_reason": "string",
  "overlap_policy": "string",
  "behaviors": {
    "create_prs": true,
    "watch_ci": true,
    "fix_review_comments": true,
    "max_fix_iterations": 0
  },
  "connectors": {
    "mcp_installation_ids": [
      "string"
    ],
    "posthog_mcp_scopes": "string"
  },
  "notifications": {
    "push": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    },
    "email": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    },
    "slack": {
      "enabled": true,
      "events": [
        "string"
      ],
      "params": {}
    }
  },
  "context_target": {
    "outputs": {
      "post_to_feed": true,
      "update_context": true,
      "canvas_id": "string"
    },
    "channel_id": "string",
    "name": "string"
  },
  "internal": true,
  "origin_product": "string",
  "last_run_at": "2019-08-24T14:15:22Z",
  "last_run_status": "string",
  "last_error": "string",
  "consecutive_failures": 0,
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "triggers": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "loop_id": "48f92213-f7f6-4842-bbaf-7104e15dc651",
      "type": "string",
      "enabled": true,
      "config": {},
      "schedule_sync_status": "string",
      "last_fired_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ],
  "skill_bundles": [
    {
      "id": "string",
      "skill_name": "string",
      "skill_source": "string",
      "size": 0,
      "content_sha256": "string",
      "uploaded_at": "string"
    }
  ]
}

Status 403 Not permitted to change these fields

Status 404 Loop not found

Status 429 A per-loop trigger safety limit was reached

Delete loops

Soft delete. Pauses every trigger's schedule. Owner or a project admin only.

Required API key scopes

loop:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/loops/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/loops/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/loops/{loop_id}/".format(
        project_id=project_id,
		loop_id="<the loop id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Status 403 Not permitted to delete this loop

Status 404 Loop not found

Delete loops

Soft delete. Pauses every trigger's schedule. Owner or a project admin only.

Required API key scopes

loop:write

Path parameters

id
string

Example request

DELETE /api/projects/:project_id/loops/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl  -X DELETE \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/loops/:id/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/loops/{loop_id}/".format(
        project_id=project_id,
		loop_id="<the loop id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 204 No response body

Status 403 Not permitted to delete this loop

Status 404 Loop not found

Create loops preview

Dry run: renders the assembled instructions and trigger context for a supplied sample payload (or a synthetic schedule fire when omitted), without creating a task, run, or any other side effect.

Required API key scopes

loop:read

Path parameters

id
string

Request parameters

trigger_type
Default: schedule
payload

Response

Example request

POST /api/projects/:project_id/loops/:id/preview
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/loops/:id/preview/\
	-d trigger_type=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/loops/{loop_id}/preview/".format(
        project_id=project_id,
		loop_id="<the loop id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "instructions": "string",
  "trigger_type": "string",
  "trigger_context": "string"
}

Status 404 Loop not found

Create loops preview

Dry run: renders the assembled instructions and trigger context for a supplied sample payload (or a synthetic schedule fire when omitted), without creating a task, run, or any other side effect.

Required API key scopes

loop:read

Path parameters

id
string

Request parameters

trigger_type
Default: schedule
payload

Response

Example request

POST /api/projects/:project_id/loops/:id/preview
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/loops/:id/preview/\
	-d trigger_type=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/loops/{loop_id}/preview/".format(
        project_id=project_id,
		loop_id="<the loop id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200

RESPONSE
{
  "instructions": "string",
  "trigger_type": "string",
  "trigger_context": "string"
}

Status 404 Loop not found

Create loops run

Manual fire from the UI. Owner-only for personal loops; any team member for team loops.

Required API key scopes

loop:write

Path parameters

id
string

Response

Example request

POST /api/projects/:project_id/loops/:id/run
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/loops/:id/run/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/loops/{loop_id}/run/".format(
        project_id=project_id,
		loop_id="<the loop id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "created": true,
  "reason": "created",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b"
}

Status 403 Not permitted to run this loop

Status 404 Loop not found

Create loops run

Manual fire from the UI. Owner-only for personal loops; any team member for team loops.

Required API key scopes

loop:write

Path parameters

id
string

Response

Example request

POST /api/projects/:project_id/loops/:id/run
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/loops/:id/run/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/loops/{loop_id}/run/".format(
        project_id=project_id,
		loop_id="<the loop id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "created": true,
  "reason": "created",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b"
}

Status 403 Not permitted to run this loop

Status 404 Loop not found

Retrieve loops runs

Run history for a loop, newest first, cursor-paginated.

Required API key scopes

loop:read

Path parameters

id
string

Query parameters

cursor
string
limit
integer
Default: 50
status
string
One of: "not_started""queued""in_progress""completed""failed""cancelled"

Response

Example request

GET /api/projects/:project_id/loops/:id/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/loops/:id/runs/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/loops/{loop_id}/runs/".format(
        project_id=project_id,
		loop_id="<the loop id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Run history page

RESPONSE
{
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
      "loop_trigger_id": "3886cea5-777d-4e3c-b81c-9ef3c5fc971d",
      "status": "string",
      "environment": "string",
      "branch": "string",
      "error_message": "string",
      "output": {},
      "created_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z"
    }
  ],
  "next_cursor": "string"
}

Status 404 Loop not found

Retrieve loops runs

Run history for a loop, newest first, cursor-paginated.

Required API key scopes

loop:read

Path parameters

id
string

Query parameters

cursor
string
limit
integer
Default: 50
status
string
One of: "not_started""queued""in_progress""completed""failed""cancelled"

Response

Example request

GET /api/projects/:project_id/loops/:id/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/loops/:id/runs/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/loops/{loop_id}/runs/".format(
        project_id=project_id,
		loop_id="<the loop id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Run history page

RESPONSE
{
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
      "loop_trigger_id": "3886cea5-777d-4e3c-b81c-9ef3c5fc971d",
      "status": "string",
      "environment": "string",
      "branch": "string",
      "error_message": "string",
      "output": {},
      "created_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z"
    }
  ],
  "next_cursor": "string"
}

Status 404 Loop not found

Create loops trigger

Authenticated POST trigger for type=api triggers. Project secret API key auth (loop:write scope), project-wide. Request body (JSON, capped at 64 KB) becomes run context. Send an Idempotency-Key header to dedupe retries.

Required API key scopes

loop:write

Path parameters

id
string

Response

Example request

Example response

Status 200

RESPONSE
{
  "created": true,
  "reason": "created",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b"
}

Status 404 Loop not found

Status 413 Request body exceeds 64 KB

Create loops trigger

Required API key scopes

loop:write

Path parameters

id
string

Response

Example request

Example response

Status 200

RESPONSE
{
  "created": true,
  "reason": "created",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b"
}