List a project's research

curl https://api.example.test/v1/projects/$PROJECT_ID/research \  -H "Authorization: Bearer $TOKEN"

Every run, newest first, each with where it stands, how many notes it wrote and suggestions it left, which provider and model answered, who asked, when, and the notes themselves: topic, summary as sanitised HTML and the sources cited.

Requires ability

import:view-any

The token must hold this ability, or the call is refused with 403.

MCP tools

list_council_sessions list_import_batches list_research_notes

Run the same action from an agent, behind the same ability.

Authorization

bearerToken

AuthorizationBearer <token>

A personal access token minted in the app under Account Settings, then API Tokens, sent as Authorization: Bearer zg_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team, and optionally to one project, at mint time.

In: header

Path Parameters

project*string

The project.

Formatuuid

Responses

200OKapplication/json

Array of ResearchRunResource

data*array<>

The items.

401UnauthorizedAUTHENTICATION_REQUIREDapplication/json

The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (a zg_test_ token on production).

error*

The one envelope every failure uses.

403ForbiddenTOKEN_MISSING_ABILITYapplication/json

The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who registered a row answers FORBIDDEN with the same status, and says so in its own description. On this endpoint: FORBIDDEN: when the token is a client guest's, or the holder's role on the project does not carry import:view-any.

error*

The one envelope every failure uses.

404Not foundRESOURCE_NOT_FOUNDapplication/json

An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred. On this endpoint: RESOURCE_NOT_FOUND: when the project is hidden from the token or missing.

error*

The one envelope every failure uses.

429Too many requestsRATE_LIMITEDapplication/json

The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.

error*

The one envelope every failure uses.

Call it from your code

A sample request in your language, the body each status answers with, and the types to hold them.

curl -X GET "https://example.com/v1/projects/497f6eca-6276-4993-bfeb-53cbbbba6f08/research"

{  "data": [    {      "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a60",      "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",      "status": "ready",      "note_count": 2,      "suggestion_count": 3,      "provider": "anthropic",      "model": "the model the research role is configured with",      "usage_id": "c9d0e1f2-a3b4-4c5d-8e6f-7a8b9c0d1e23",      "failure_reason": null,      "created_by": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",      "creator_name": "Jane Doe",      "started_at": "2026-10-28T14:00:05+00:00",      "finished_at": "2026-10-28T14:03:00+00:00",      "created_at": "2026-10-28T14:00:00+00:00",      "notes": [        {          "id": "f2a3b4c5-d6e7-4f8a-9b0c-1d2e3f4a5b71",          "run_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a60",          "position": 1,          "topic": "Loyalty programmes in retail",          "summary": "<p>Points schemes tie points to spend, expire them after a year and tier members by yearly spend; the leading schemes let points pay part of an order at checkout.</p>",          "sources": [            "https://example.com/loyalty-programmes"          ],          "created_at": "2026-10-28T14:03:00+00:00"        },        {          "id": "a3b4c5d6-e7f8-4a9b-8c1d-2e3f4a5b6c82",          "run_id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a60",          "position": 2,          "topic": "Data protection for customer accounts",          "summary": "<p>A shop that keeps customer accounts must state what it keeps and for how long, let a customer export and delete their data, and keep consent for marketing apart from the account.</p>",          "sources": [            "https://example.com/data-protection-retail"          ],          "created_at": "2026-10-28T14:03:00+00:00"        }      ]    }  ]}

Type definitions

The shapes above as types, ready to paste into your client.

export interface Response {  data: ResearchRunResource[];}export interface ResearchRunResource {  id: string;  project_id: string;  status: string;  note_count: number;  suggestion_count: number;  provider: string | null;  model: string | null;  usage_id: string | null;  failure_reason: string | null;  created_by: string | null;  creator_name: string | null;  started_at: string | null;  finished_at: string | null;  created_at: string | null;  notes?: ResearchNoteResource[];}export interface ResearchNoteResource {  id: string;  run_id: string;  position: number;  topic: string;  summary: string;  sources: string[];  created_at: string | null;}

List a project's research

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

ResponsesCopy Anchor Link

Authorization

Path Parameters

Responses