Projects

Get a project

Returns one project you are a member of, and your role in it. An id you are not a member of — including one that does not exist — responds 404, not 403: the API never confirms that an id exists elsewhere. 403 is reserved for the cases where there is nothing to hide: a project you are in, addressed with a credential scoped to a different one, or an action your role does not carry. There the message is what makes the failure fixable.

get/v1/projects/{project_id}

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Response

Project details.

idstring required

Public project ID (proj_ prefix).

namestring required
status'active' | 'archived' required
role'owner' | 'admin' | 'member' required

What the member may do in this project. owner — everything, including deleting it and paying for it; exactly one per project. admin — everything a member may do, plus managing who else is in the project and how the project itself is configured. member — every read and write on the project's own resources, including minting project API keys. When returned on a Project, this is your role, not a property of the project: it is what lets a client hide an action the request would refuse.

owner_user_idstring required

The user who pays for the project — its billing owner, and the one member holding the owner role. Membership decides who may act in a project; this decides who is charged for it.

transfer_to_user_idstring nullable required

The member a pending transfer would make the owner, until they accept or decline it; null when none is pending.

trace_content_retention_daysinteger nullable required

How long trace and generation content is kept before a daily sweep purges it. null (the default) disables retention, so content is kept until purged on demand. A swept record is content-purged the same way an on-demand purge does it — the row survives as an auditable skeleton with content_redacted_at set.

trace_content_mode'full' | 'none' required

Whether trace and generation content is persisted at all. full (the default) stores it; none is zero-retention — content is never written, for every agent in this project. none is a floor, not a default: an agent may tighten itself to none, but cannot loosen a none project back to full.

max_concurrent_runsinteger nullable required

Orchestration runs of this project driven at once. null (the default) is unlimited. Enforced when a run is claimed — runs past the limit wait for a slot rather than failing.

max_chain_generationsinteger nullable required

Generations one continuation chain in this project may hold before it stops being resumed. null (the default) leaves the platform-wide ceiling in force. The budget actually applied is the smallest of that ceiling, this number, and the agent's own — an agent author can be stricter than this, never looser.

max_orchestration_run_depthinteger nullable required

Nesting levels a run tree in this project may reach before the next child is refused. null (the default) leaves the platform-wide bound in force; the bound applied is the smaller of the two.

require_priced_modelboolean required

Whether a generation whose model carries no price is refused before the provider is called. false by default, which runs the model and meters it at no cost. Mainly of use with your own providers — see Requiring a priced model.

guardrail_idsstring[] required

Guardrails attached at the project scope — the floor under every tool call by every agent in the project, including tools added later. Empty by default. See Attaching one.

paused_atstring date-time nullable required

When the project was paused; null while it runs. See Pausing a project.

pause_reasonstring nullable required

The reason the pause named; null while the project runs, or when the pause named none.

managed_conversionboolean required

Whether scanned PDFs, images and audio are converted to text on ingest with no setup. true by default. See Managed conversion.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "id": "proj_V1StGXR8Z5jdHi6B",
  "name": "acme-perpetual",
  "status": "active",
  "role": "owner",
  "owner_user_id": "user_V1StGXR8Z5jdHi6B",
  "trace_content_mode": "full",
  "guardrail_ids": [],
  "managed_conversion": true,
  "created_at": "2026-07-17T00:00:00.000Z",
  "updated_at": "2026-07-17T00:00:00.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.