Projects

📁 Projects

A project is the container every file and every analysis belongs to. Its numeric ID is the one value the rest of this reference assumes you already have: project when you upload a file, project_id on every call center read endpoint.

There are two ways to get it:

From the API — GET /api/projects/ lists every project your key can see, with its ID.
From the web app — see Finding the ID in the web app below.

All endpoints here require either a session cookie or an API key — see Authentication.

GET /api/projects/

List the projects visible to the caller, newest first.

Auth: API key or session.

Query parameters:

Parameter	Required	Description
`project_type`	no	Filter by type: `audio` or `survey`. Call center and interview projects are both `audio` — they’re told apart by `audio_type`.
`team`	no	Restrict to one team’s projects, by team ID. Silently ignored if the team doesn’t exist or the key’s user isn’t a member of it — you get the default unfiltered list back, not an error, so check the `team` field on the results if it matters.

Response (200 OK):

Results are paginated, 100 per page. Follow next if you have more projects than that.

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 312,
      "name": "Sales — June",
      "project_type": "audio",
      "description": "",
      "status": "created",
      "user": 87,
      "team": 4,
      "created_at": "2026-06-01T09:14:52Z",
      "updated_at": "2026-06-28T17:31:06Z",
      "audio_type": "call",
      "return_timestamps": false,
      "default_language": "es",
      "metadata": null,
      "shared_with": [91, 104],
      "survey_template": null,
      "evaluation_rubric": 7,
      "predefined_codes": null,
      "auto_analysis_enabled": true,
      "auto_analysis_types": ["calls_analysis_copc"],
      "auto_analysis_questions": null,
      "auto_analysis_batch_size": 20,
      "auto_analysis_max_wait_seconds": 300,
      "analyzed_custom_question_calls": 0
    },
    { "…": "one object per project" }
  ]
}

The fields you’ll actually use:

Field	Description
`id`	What you pass as `project` or `project_id` everywhere else.
`name`	The name shown in the web app’s project selector.
`project_type`	`audio` (recordings) or `survey` (spreadsheet responses).
`audio_type`	`call`, `interview` or `focus_group`. Call center features only apply to `call` projects.
`status`	`created`, `processing`, `completed` or `failed`. Deleted projects are never returned.
`team`	The owning team’s ID, or `null` for a personally-owned project.
`auto_analysis_enabled`	Whether calls are analyzed automatically as they arrive. See Uploading Calls for Analysis.
`shared_with`	IDs of users the project has been explicitly shared with.

One field to be aware of: metadata is a free-form JSON blob, and on call projects it also holds any CSV manifest rows that haven’t matched a file yet — so it can be very large. Skip it unless you put something there yourself.

Which projects come back: your own projects, every project in a team where you are an admin, and any project explicitly shared with you. Deleted projects are excluded. A key inherits its user’s view of the system exactly — see Scoping.

Example — list your call center projects:

audio_type isn’t a server-side filter, so ask for project_type=audio and filter the results.

curl -sS "https://app.uspeech.io/api/projects/?project_type=audio" \
  -H "Authorization: Api-Key $USPEECH_KEY" \
  | jq -r '.results[] | select(.audio_type == "call") | "\(.id)\t\(.name)"'

import os

import requests

BASE_URL = "https://app.uspeech.io"
HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}

response = requests.get(
    f"{BASE_URL}/api/projects/",
    headers=HEADERS,
    params={"project_type": "audio"},
    timeout=30,
)
response.raise_for_status()

for project in response.json()["results"]:
    if project["audio_type"] == "call":
        print(project["id"], project["name"])

const BASE_URL = 'https://app.uspeech.io';
const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };

const response = await fetch(`${BASE_URL}/api/projects/?project_type=audio`, { headers: HEADERS });
if (!response.ok) throw new Error(await response.text());

const { results } = await response.json();
for (const project of results.filter((p) => p.audio_type === 'call')) {
  console.log(project.id, project.name);
}

💡 Tip: look the ID up once and store it in your integration’s configuration. Project IDs are stable — they never change for the life of the project.

GET /api/projects/{id}/

Read a single project. Returns the same object as one entry of the list above.

Auth: API key or session.

Useful for confirming a project is a call project (audio_type) and checking whether automatic analysis is on before you start uploading.

curl -sS https://app.uspeech.io/api/projects/312/ \
  -H "Authorization: Api-Key $USPEECH_KEY"

import os

import requests

BASE_URL = "https://app.uspeech.io"
HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}
project_id = 312

response = requests.get(f"{BASE_URL}/api/projects/{project_id}/", headers=HEADERS, timeout=30)
response.raise_for_status()
project = response.json()

print(project["name"], project["audio_type"], project["auto_analysis_enabled"])

const BASE_URL = 'https://app.uspeech.io';
const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };
const projectId = 312;

const response = await fetch(`${BASE_URL}/api/projects/${projectId}/`, { headers: HEADERS });
if (!response.ok) throw new Error(await response.text());
const project = await response.json();

console.log(project.name, project.audio_type, project.auto_analysis_enabled);

A 404 Not Found here means the project exists but isn’t visible to the key’s user — check that the user owns it, admins its team, or has had it shared with them.

To change a project’s automatic-analysis settings, use PATCH /api/projects/{id}/; the configurable fields and their validation rules are documented in Uploading Calls for Analysis.

Finding the ID in the web app

If you’d rather read the ID off the screen than call the API:

Open Conversations in the web app.
Pick the project in the selector at the top of the page.
The ID is shown in the Upload Files card, next to the Upload via API link.

Projects you create programmatically with POST /api/projects/ return their new id in the 201 Created response, so there’s no lookup step in that case.

Where the ID is used

Transcription — project on POST /api/files/
Uploading Calls for Analysis — the whole walkthrough
Call Metadata — POST /api/projects/{id}/call-manifest/
Call Reports — project_id on every report endpoint