Skip to content
For AI agents: every API docs page in one plain-text file is at /docs/llms-full.txt, and the documentation index is at /llms.txt. This page is available as Markdown at https://diffio.ai/docs/api-reference/get-project.md, and every docs URL returns Markdown when requested with Accept: text/markdown.

Get a project
Returns one project, including its upload status, probed duration_seconds and has_video, active share_id, and latest_generation.
GET https:/
- Key scope:
projects:read - Auth header:
Authorization: Bearer <apiKey> - Body: None
Request
Pass project_id in the path; takes no request body.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
#project_id | string | Required: Yes | Unique identifier of the project. |
Headers
| Field | Type | Required | Description |
|---|---|---|---|
#Diffio-End-User | string | Required: No | Optional end-user identifier (up to 128 characters). Scopes the request to that end user's projects; omit to act across the whole account. |
Request
import os
from diffio import DiffioClient
key = os.environ["DIFFIO_API_KEY"]
client = DiffioClient(api_key=key)
project = client.projects.get(
"62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
)Response
Returns the project object.
Success: 200OK.
Response fields
| Field | Type | Present | Description |
|---|---|---|---|
#id | string | Always | Unique project identifier (UUID). |
#object | string | Always | Resource type, always "project".project |
#status | string | Always | Upload and preparation state: awaiting_upload until bytes arrive, preparing while media is probed, ready when ready to restore, or failed.awaiting_uploadpreparingreadyfailed |
#file_name | string | null | Always | Recording filename as sent at creation, or null. |
#content_type | string | null | Always | MIME type sent at creation (application/octet-stream when none was sent), or null. |
#size_bytes | integer | null | Always | File size in bytes: the uploaded byte count once the upload arrives, before that the size_bytes sent at creation; null when unknown. |
#duration_seconds | number | null | Always | Recording duration in seconds once status is ready, or null while awaiting upload or preparing. |
#has_video | boolean | Always | True when the recording has video: inferred from content_type or the file name until the upload is probed, then from the file itself. |
Show all 19 fields (11 more)
| Field | Type | Present | Description |
|---|---|---|---|
#end_user | string | null | Always | End-user identifier from the Diffio-End-User header at creation, or null for account-level projects. |
#metadata | object | Always | Key-value string map saved with the project ({} when none was supplied). |
#generation_count | integer | Always | Total number of generations created for this project. |
#video_preview_status | string | null | Always | State of a video project's picture-only HLS stream (video_hls): preparing, ready, or failed; null for audio projects.preparingreadyfailed |
#share_id | string | null | Always | Public 17-character share identifier while a share is published, or null when unshared. |
#latest_generation | object | null | Always | Newest Generation object on this project, or null when no generation exists yet. |
#created_at | string | null | Always | ISO 8601 UTC timestamp when the project was created, or null. |
#updated_at | string | null | Always | ISO 8601 UTC timestamp when the project last changed, or null. |
#error | object | null | Always | Failure details when status is failed, or null otherwise. |
#error. | string | Always | Stable snake_case project failure code (media_processing_failed or project_failed). |
#error. | string | Always | Human-readable explanation of why the upload could not be prepared. |
Response 200OK.
Successful response
{
"id": "62f62565-049f-5e7e-bbd2-9de0cf7ddbfe",
"object": "project",
"status": "awaiting_upload",
"file_name": "interview.mp3",
"content_type": "audio/mpeg",
"size_bytes": 510957,
"duration_seconds": null,
"has_video": false,
"end_user": "customer-mwe8tm1g",
"metadata": {
"order_id": "1042"
},
"generation_count": 0,
"video_preview_status": null,
"latest_generation": null,
"share_id": null,
"created_at": "2026-11-13T00:33:21.812909Z",
"updated_at": "2026-11-13T00:33:21.812909Z",
"error": null
}Return codes
200OK.Returns the requested project.400Bad request.Diffio-End-Userexceeds 128 characters.invalid_header403Forbidden: the key lacks permission.Key is inactive or lacksprojects:read.permission_denied404Not found.No project with thatproject_idexists for this account and end user.project_not_found401Unauthorized: the API key is missing or invalid.405Client error.Same on every endpoint401Unauthorized: the API key is missing or invalid. Missing API key (code missing_api_key), or invalid API key (code invalid_api_key).405Client error. HTTP method not supported on this path; check the Allow header (code method_not_allowed).
Example error response
Errors are JSON: an error object with code, message and request_id. An unrecognized key returns 401Unauthorized: the API key is missing or invalid.:
Error response
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key.",
"request_id": "dead773b60e148fd9e22d680a22fa701"
}
}Notes
statustransitions fromawaiting_uploadtopreparingtoready(orfailedwitherrorif the uploaded file cannot be decoded).- Once
statusisready,duration_secondsandhas_videoreflect the probed file;size_bytesis the uploaded byte count from when the upload arrives. - Upload credentials are not returned here; call Get new upload instructions if an upload has not arrived yet.