> For the documentation index, fetch https://sync.so/docs/llms.txt. Append .md to a page URL for Markdown. Documentation-search MCP: https://sync.so/docs/_mcp/server.

# List Projects

GET https://api.sync.so/v2/projects

List the projects in your organization, most recently updated first.

Reference: https://sync.so/docs/api-reference/api/projects-api/list

## Authentication

- `x-api-key` header (required) — API Key authentication via header

## Servers

- `https://api.sync.so` (Default, default)
- `https://dev-api.sync.so` (dev)
- `http://localhost:3001` (local)

## Request

### Query parameters

- `limit` (integer, optional) — Maximum number of projects to return (1-100). Defaults to 10.
- `cursor` (string, optional) — Cursor for pagination.
- `searchQuery` (string, optional) — Search projects by name.
- `sortBy` (enum, optional) — Sort order for the results. Defaults to updatedAt.
  - Allowed values: `updatedAt`, `name`

## Response

### 200

Projects retrieved successfully

- `items` (list of ProjectListItem, required) — Array of projects.
- `nextCursor` (string, optional) — Cursor for fetching the next page of results.

## Errors

### 401 Unauthorized Error

Unauthorized - Invalid or missing authentication

- `message` (GenerationErrorMessage, required) — A message describing the error.
- `statusCode` (double, required) — The type of error that occurred.
- `errorCode` (string, optional) — Stable, machine-readable error code (e.g. project_not_found, voice_not_found, concurrency_limit_reached). Branch your error handling on this, not on the message text. The full catalog of codes with messages and suggested fixes is served unauthenticated at GET /v2/errors.
- `suggestion` (string, optional) — A suggested fix an agent can act on.
- `field` (string, optional) — The request field the error refers to, when the failure is tied to a specific field (e.g. projectId, voiceId, input[].assetId).
- `docsUrl` (string, optional) — Link to the documentation page for the failing operation.
- `requestId` (string, optional) — Present on unexpected 500 responses. Include it when contacting support so the failing request can be located directly.
- `generationId` (string, optional) — Original generation ID when available for an uncertain keyed submission. Poll this ID; do not create another action to bypass IDEMPOTENCY_OUTCOME_UNKNOWN.
- `dialogueEditSection` (DialogueEditRetimeFailureSection, optional) — For dialogue_edit_removal_too_large: the section to change, when it can be identified. Create a new dialogue edit preview before submitting again.

### 500 Internal Server Error

Internal Server Error - An unexpected failure on our side. The body carries errorCode internal_error and a requestId; include the requestId when contacting support.

- `message` (GenerationErrorMessage, required) — A message describing the error.
- `statusCode` (double, required) — The type of error that occurred.
- `errorCode` (string, optional) — Stable, machine-readable error code (e.g. project_not_found, voice_not_found, concurrency_limit_reached). Branch your error handling on this, not on the message text. The full catalog of codes with messages and suggested fixes is served unauthenticated at GET /v2/errors.
- `suggestion` (string, optional) — A suggested fix an agent can act on.
- `field` (string, optional) — The request field the error refers to, when the failure is tied to a specific field (e.g. projectId, voiceId, input[].assetId).
- `docsUrl` (string, optional) — Link to the documentation page for the failing operation.
- `requestId` (string, optional) — Present on unexpected 500 responses. Include it when contacting support so the failing request can be located directly.
- `generationId` (string, optional) — Original generation ID when available for an uncertain keyed submission. Poll this ID; do not create another action to bypass IDEMPOTENCY_OUTCOME_UNKNOWN.
- `dialogueEditSection` (DialogueEditRetimeFailureSection, optional) — For dialogue_edit_removal_too_large: the section to change, when it can be identified. Create a new dialogue edit preview before submitting again.

## Types

### ProjectListItem

A project as returned in the list-projects response.

- `completedGenerationsCount` (double, required) — Completed undeleted generations with an output file.
- `createdAt` (datetime, required) — The date and time the project was created.
- `deletedAt` (datetime, required, nullable)
- `generations` (list of ProjectGeneration, required) — Zero or one item, the most recent undeleted generation.
- `generationsCount` (double, required) — Number of undeleted generations in the project.
- `id` (string, required) — A unique identifier for a project.
- `lastGenerationSource` (string, required, nullable) — Source metadata of the most recent generation; null when absent.
- `latestAssetAttachedAt` (datetime, required, nullable) — When the project's most recent visual asset was attached, so clients can rank it against the latest generation by recency. Null when the project has no such asset.
- `latestAssetThumbnailUrl` (string, required, nullable) — Preview for the project's most recent visual asset: a video's thumbnail, or an image's own URL. Null when the project has no video with a thumbnail or image.
- `mode` (enum, required) — The project mode.
  - Allowed values: `CREATOR`, `DEVELOPER`
- `organizationId` (string, required)
- `updatedAt` (datetime, required) — The date and time the project was last updated.
- `userId` (string, required, nullable)
- `visibility` (enum, required) — Who can see the project.
  - Allowed values: `USER`, `ORGANIZATION`
- `assets` (list of any, required, deprecated) — Deprecated compatibility field; always an empty array in project listings.
- `generationPresets` (list of any, required, deprecated) — Deprecated compatibility field; always an empty array in project listings.
- `defaultWorkflow` (enum, optional, nullable) — The default top-level creator workflow for this project. Null for projects created outside the creator-workflows surface.
  - Allowed values: `lipsync`, `translate_and_dub`, `change_appearance`, `image_to_video`, `edit_dialogue`, `assistant`, `timeline`
- `description` (string, optional) — An optional description of the project.
- `name` (string, optional) — The display name of the project.

### GenerationErrorMessage

A message describing the error.

### DialogueEditRetimeFailureSection

The dialogue-edit section that removes too much speech to stay in sync.

- `slotIndex` (integer, required) — Zero-based index of the section in the preview's `resultSlots`.
- `sourceStartMs` (integer, optional) — Start of the section in the source video, in absolute milliseconds.
- `sourceDurationMs` (integer, optional) — Length of the section in the source video, in milliseconds.

### ProjectGeneration

The latest undeleted generation on a project-list item, using the stored-generation response shape.

- `id` (string, required) — A unique identifier for the generation.
- `organizationId` (string, required)
- `userId` (string, required, nullable)
- `apiKeyId` (string, required, nullable)
- `createdAt` (datetime, required)
- `updatedAt` (datetime, required)
- `startedAt` (datetime, required, nullable)
- `finishedAt` (datetime, required, nullable)
- `status` (enum, required) — The status of the generation.
  - Allowed values: `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `REJECTED`
- `model` (ProjectGenerationModel, required)
- `modelName` (string, required)
- `inputs` (list of ProjectGenerationInput, required)
- `webhookUrl` (string, required, nullable)
- `thumbnailUrl` (string, required, nullable)
- `frameCount` (double, required, nullable)
- `options` (map from string to any, required) — Persisted generation options, including server-owned fields. This is not a create-request options contract.
- `outputMediaUrl` (string, required, nullable)
- `segmentOutputMediaUrl` (string, required, nullable)
- `segmentOutputBucketPath` (string, required, nullable)
- `outputMediaLength` (double, required, nullable)
- `potentialError` (ProjectGenerationError, required, nullable)
- `isPublic` (boolean, required, nullable)
- `deletedAt` (datetime, required, nullable)
- `projectId` (string, required, nullable) — A unique identifier for a project.
- `segments` (list of ProjectGenerationSegment, optional, nullable)
- `creatorName` (string, optional, nullable)
- `outputFileName` (string, optional, nullable)
- `outputExtension` (string, optional, nullable)
- `generationEstimate` (GenerationEstimate, optional, nullable) — A completion-time estimate produced when a generation is accepted.

### ProjectGenerationModel

- `id` (string, required)
- `name` (string, required)
- `description` (string, required, nullable)
- `type` (string, required)
- `version` (string, required)
- `features` (list of string, required)
- `deprecatedAt` (datetime, required, nullable)

### ProjectGenerationInput

Stored input metadata. Fields generated by the server are response-only.

- `type` (string, required)
- `url` (string, optional)
- `assetId` (string, optional) — A unique identifier for an asset.
- `refId` (string, optional)
- `generatedBy` ("tts", optional)
- `segments_secs` (list of list of double, optional)
- `segments_frames` (list of list of double, optional)
- `trim_secs` (list of double, optional)
- `provider` (ProjectGenerationProvider, optional)

### ProjectGenerationError

- `message` (string, required)
- `status` (double, optional)
- `errorCode` (string, optional)
- `docsLink` (string, optional)

### ProjectGenerationSegment

- `startTime` (double, optional)
- `endTime` (double, optional)
- `startFrame` (double, optional)
- `endFrame` (double, optional)
- `audioInput` (SegmentAudioInput, optional) — Audio input configuration for a specific segment. References an audio input by refId and optionally crops the audio to a specific time range.
- `optionsOverride` (map from string to any, optional) — Stored segment-specific options, including server-owned fields.

### GenerationEstimate

A completion-time estimate produced when a generation is accepted.

- `estimatedDurationSeconds` (double, required) — Estimated generation duration in seconds.
- `estimatedFinishAt` (datetime, required) — Estimated completion timestamp a client shows for the remaining wait.
- `delayedAt` (datetime, required) — Timestamp after which the generation is considered delayed relative to the estimate.
- `supportAt` (datetime, required) — Timestamp after which contacting support is suggested.
- `estimatedAt` (datetime, required) — When the estimate was computed.
- `serverTime` (datetime, required) — Current server time, stamped when the response was built.
- `calibrationAsOf` (datetime, required) — When the calibration snapshot behind the estimate was last refreshed.
- `estimatorVersion` (string, required) — Version of the estimator that produced the estimate.
- `confidence` (enum, required) — The estimate's confidence level.
  - Allowed values: `measured`, `approximate`, `fallback`
- `source` (enum, required) — The data source the estimate was derived from.
  - Allowed values: `cohort`, `duration_neighbor`, `resolution_neighbor`, `model_pool`, `global_pool`, `fallback`
- `sampleCount` (integer, required) — Number of historical samples that informed the estimate.
- `scope` (enum, required) — Whether the generation is a Studio or non-Studio generation.
  - Allowed values: `studio`, `non_studio`
- `durationBand` (string, required) — Duration bucket used to match the estimate against similar past generations.
- `resolutionBand` (string, required) — Resolution bucket used to match the estimate against similar past generations.
- `resolutionSource` (enum, required) — Whether the resolution came from the requested output, the input asset, or is unknown.
  - Allowed values: `input`, `requested_output`, `unknown`

### ProjectGenerationProvider

- `name` (string, required)
- `script` (string, required)
- `voiceId` (string, required)
- `stability` (double, optional)
- `similarityBoost` (double, optional)

### SegmentAudioInput

Audio input configuration for a specific segment. References an audio input by refId and optionally crops the audio to a specific time range.

- `refId` (string, required) — Reference ID of the audio/text-to-speech input to use for this segment
- `startTime` (double, optional) — Optional start time (in seconds) to crop the referenced audio. When specified, endTime must also be provided, and startTime must be less than or equal to endTime.
- `endTime` (double, optional) — Optional end time (in seconds) to crop the referenced audio. When specified, startTime must also be provided, and must be greater than or equal to startTime.

## Examples

**Response**

```json
{
  "items": [
    {
      "completedGenerationsCount": 0,
      "createdAt": "2024-01-15T09:30:00Z",
      "deletedAt": null,
      "generations": [],
      "generationsCount": 0,
      "id": "612bb64a-e7f4-40c1-977b-3e9797845637",
      "lastGenerationSource": null,
      "latestAssetAttachedAt": null,
      "latestAssetThumbnailUrl": null,
      "mode": "CREATOR",
      "organizationId": "1f8a0c42-3ae1-4a0a-a17c-b333c11d2835",
      "updatedAt": "2024-01-15T09:30:00Z",
      "userId": null,
      "visibility": "USER",
      "assets": [],
      "generationPresets": [],
      "name": "My API Project"
    }
  ],
  "nextCursor": "cursor_abc123"
}
```

**SDK Code**

```python
import requests

url = "https://api.sync.so/v2/projects"

querystring = {"limit":"10","sortBy":"updatedAt"}

headers = {"x-api-key": "<apiKey>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.sync.so/v2/projects?limit=10&sortBy=updatedAt';
const options = {method: 'GET', headers: {'x-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sync.so/v2/projects?limit=10&sortBy=updatedAt"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.sync.so/v2/projects?limit=10&sortBy=updatedAt")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.sync.so/v2/projects?limit=10&sortBy=updatedAt")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.sync.so/v2/projects?limit=10&sortBy=updatedAt', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.sync.so/v2/projects?limit=10&sortBy=updatedAt");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["x-api-key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sync.so/v2/projects?limit=10&sortBy=updatedAt")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```