> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Projects

> Retrieve a list of all projects associated with your Pictory account

## Overview

Retrieve a list of all projects associated with your Pictory account. Projects represent video creation workflows at various stages, including those created from scripts, video/audio transcriptions, or URLs.

<Note>
  You need a valid API key to use this endpoint. Get your API key from the [API Access page](https://app.pictory.ai/api-access) in your Pictory dashboard.
</Note>

***

## API Endpoint

```http theme={null}
GET https://api.pictory.ai/pictoryapis/v2/projects
```

***

## Request Parameters

### Headers

<ParamField header="Authorization" type="string" required>
  API key for authentication (starts with `pictai_`)

  ```
  Authorization: YOUR_API_KEY
  ```
</ParamField>

### Query Parameters

<ParamField query="pagekey" type="string">
  Pagination token for retrieving the next page of results. Pass this value exactly as received from the `pageKey` field in the previous API response.
</ParamField>

<ParamField query="folder" type="string">
  Filter to retrieve projects from a specific folder by folder ID
</ParamField>

***

## Response

<ResponseField name="items" type="array of objects">
  Array of project objects

  <Expandable title="project item">
    <ResponseField name="id" type="string | integer">
      Unique identifier for the project. Can be a string (for v3 schema) or integer (for v2 schema and earlier)
    </ResponseField>

    <ResponseField name="name" type="string">
      Name of the project
    </ResponseField>

    <ResponseField name="source" type="string">
      Source type of the project

      **Possible values:**

      * `script` - Created from text/script
      * `transcribe` - Created from video/audio transcription
      * `url` - Created from URL
    </ResponseField>

    <ResponseField name="projectPreview" type="string | null">
      URL to the project preview image or video. May be `null` if no preview is available.
    </ResponseField>

    <ResponseField name="savedDate" type="string">
      ISO 8601 timestamp of when the project was last saved
    </ResponseField>

    <ResponseField name="aspectRatio" type="string">
      Video aspect ratio of the project

      **Common values:**

      * `sixteen-nine` - 16:9 widescreen (landscape)
      * `nine-sixteen` - 9:16 vertical (portrait)
      * `onethousandsixhundredandfifty-nine-onethousandandseventy-nine` - Custom aspect ratio
    </ResponseField>

    <ResponseField name="schemaVersion" type="string | null">
      Project schema version (e.g., `v2`, `v3`). May be `null` for legacy projects.
    </ResponseField>

    <ResponseField name="type" type="string">
      Type identifier, typically `project`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pageKey" type="string | null">
  Pagination token for retrieving the next page of results. `null` if there are no more pages.
</ResponseField>

### Response Examples

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "items": [
      {
        "id": "20251222191648030d7df02f5b4054d4ca8831f1369459e25",
        "name": "Hello World Template",
        "source": "script",
        "projectPreview": "https://d3uryq9bhgb5qr.cloudfront.net/TeamsAnnual/aa46778d-7965-46e0-967d-b48ee5d6ead9/f1c3b5a7-65f9-4386-a3ef-5ac378c12fa2/image/f1c3b5a7-65f9-4386-a3ef-5ac378c12fa2.jpg",
        "savedDate": "2025-12-23T01:54:26.755Z",
        "schemaVersion": "v3",
        "type": "project"
      },
      {
        "id": 1762768083800,
        "name": "my_saved_project",
        "source": "script",
        "projectPreview": "https://media.gettyimages.com/id/2161111014/video/create-social-media-content.mp4",
        "savedDate": "2025-11-10T09:48:03.800Z",
        "aspectRatio": "sixteen-nine",
        "schemaVersion": "v2",
        "type": "project"
      },
      {
        "id": 1751663566232,
        "name": "What_is_Calculus",
        "source": "transcribe",
        "projectPreview": null,
        "savedDate": "2025-07-04T21:13:26.094Z",
        "aspectRatio": "sixteen-nine",
        "type": "project"
      }
    ],
    "pageKey": null
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "message": "Unauthorized"
  }
  ```
</ResponseExample>

***

## Code Examples

<Tip>
  Replace `YOUR_API_KEY` with your actual API key that starts with `pictai_`
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.pictory.ai/pictoryapis/v2/projects' \
    --header 'Authorization: YOUR_API_KEY' \
    --header 'accept: application/json' | python -m json.tool
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.pictory.ai/pictoryapis/v2/projects"
  headers = {
      "Authorization": "YOUR_API_KEY",
      "accept": "application/json"
  }

  response = requests.get(url, headers=headers)
  projects = response.json()

  # Print project details
  for project in projects['items']:
      print(f"Project: {project['name']}")
      print(f"  ID: {project['id']}")
      print(f"  Source: {project['source']}")
      print(f"  Saved: {project['savedDate']}")
      print("---")
  ```

  ```javascript JavaScript / Node.js theme={null}
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v2/projects',
    {
      method: 'GET',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'accept': 'application/json'
      }
    }
  );

  const data = await response.json();

  // Print project details
  data.items.forEach(project => {
    console.log(`Project: ${project.name}`);
    console.log(`  ID: ${project.id}`);
    console.log(`  Source: ${project.source}`);
    console.log(`  Saved: ${project.savedDate}`);
    console.log('---');
  });
  ```

  ```php PHP theme={null}
  <?php
  // Replace 'YOUR_API_KEY' with your actual API key

  function getProjects($apiKey) {
      $url = 'https://api.pictory.ai/pictoryapis/v2/projects';

      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_HTTPHEADER, [
          'Authorization: ' . $apiKey,
          'accept: application/json'
      ]);

      $response = curl_exec($ch);
      $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
      curl_close($ch);

      if ($httpCode !== 200) {
          throw new Exception('Request failed with status ' . $httpCode);
      }

      return json_decode($response, true);
  }

  // Usage
  try {
      $data = getProjects('YOUR_API_KEY');

      echo "Total projects: " . count($data['items']) . "\n\n";

      // Print project details
      foreach ($data['items'] as $project) {
          echo "Project: " . $project['name'] . "\n";
          echo "  ID: " . $project['id'] . "\n";
          echo "  Source: " . $project['source'] . "\n";
          echo "  Saved: " . $project['savedDate'] . "\n";
          echo "---\n";
      }
  } catch (Exception $e) {
      echo "Error: " . $e->getMessage() . "\n";
  }
  ?>
  ```

  ```go Go theme={null}
  // Replace "YOUR_API_KEY" with your actual API key

  package main

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

  type Project struct {
      ID             interface{} `json:"id"`
      Name           string      `json:"name"`
      Source         string      `json:"source"`
      ProjectPreview *string     `json:"projectPreview"`
      SavedDate      string      `json:"savedDate"`
      AspectRatio    string      `json:"aspectRatio,omitempty"`
      SchemaVersion  *string     `json:"schemaVersion"`
      Type           string      `json:"type"`
  }

  type ProjectsResponse struct {
      Items   []Project `json:"items"`
      PageKey *string   `json:"pageKey"`
  }

  func getProjects(apiKey string) (*ProjectsResponse, error) {
      url := "https://api.pictory.ai/pictoryapis/v2/projects"

      req, err := http.NewRequest("GET", url, nil)
      if err != nil {
          return nil, err
      }

      req.Header.Set("Authorization", apiKey)
      req.Header.Set("accept", "application/json")

      client := &http.Client{}
      resp, err := client.Do(req)
      if err != nil {
          return nil, err
      }
      defer resp.Body.Close()

      body, err := io.ReadAll(resp.Body)
      if err != nil {
          return nil, err
      }

      if resp.StatusCode != http.StatusOK {
          return nil, fmt.Errorf("request failed (status %d): %s", resp.StatusCode, string(body))
      }

      var result ProjectsResponse
      if err := json.Unmarshal(body, &result); err != nil {
          return nil, err
      }

      return &result, nil
  }

  // Usage
  func main() {
      data, err := getProjects("YOUR_API_KEY")
      if err != nil {
          panic(err)
      }

      fmt.Printf("Total projects: %d\n\n", len(data.Items))

      // Print project details
      for _, project := range data.Items {
          fmt.Printf("Project: %s\n", project.Name)
          fmt.Printf("  ID: %v\n", project.ID)
          fmt.Printf("  Source: %s\n", project.Source)
          fmt.Printf("  Saved: %s\n", project.SavedDate)
          fmt.Println("---")
      }
  }
  ```
</CodeGroup>

***

## Usage Notes

<Tip>
  Projects are returned in reverse chronological order by saved date, with the most recently saved projects appearing first.
</Tip>

<Note>
  **Pagination**: When you have many projects, use the `pageKey` value from the response to retrieve subsequent pages. Pass the `pageKey` as the `pagekey` query parameter in your next request.
</Note>

<Note>
  **Schema Versions**: Projects may have different schema versions (`v2`, `v3`, or `null`). The schema version affects the structure and capabilities of the project. Newer schema versions (v3) typically support more features.
</Note>

***

## Common Use Cases

### 1. List All Projects

Retrieve and display all projects in your account:

```python theme={null}
import requests

url = "https://api.pictory.ai/pictoryapis/v2/projects"
headers = {"Authorization": "YOUR_API_KEY"}

response = requests.get(url, headers=headers)
data = response.json()

print(f"Total projects: {len(data['items'])}")

for project in data['items']:
    print(f"{project['name']} ({project['source']})")
```

### 2. Paginate Through Projects

Handle pagination to retrieve all projects across multiple pages:

```python theme={null}
def get_all_projects(api_key):
    """
    Retrieve all projects using pagination
    """
    all_projects = []
    page_key = None
    base_url = "https://api.pictory.ai/pictoryapis/v2/projects"
    headers = {"Authorization": api_key}

    while True:
        # Build URL with page key if available
        url = f"{base_url}?pagekey={page_key}" if page_key else base_url

        response = requests.get(url, headers=headers)
        data = response.json()

        # Add projects from this page
        all_projects.extend(data['items'])

        # Check if there are more pages
        page_key = data.get('pageKey')
        if not page_key:
            break

    return all_projects

# Get all projects
projects = get_all_projects("YOUR_API_KEY")
print(f"Retrieved {len(projects)} total projects")
```

### 3. Filter Projects by Source Type

Filter projects based on how they were created:

```javascript theme={null}
const getProjectsBySource = async (sourceType) => {
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v2/projects',
    {
      headers: { 'Authorization': 'YOUR_API_KEY' }
    }
  );

  const data = await response.json();

  // Filter by source type
  const filtered = data.items.filter(p => p.source === sourceType);

  console.log(`Found ${filtered.length} ${sourceType} projects`);
  return filtered;
};

// Get only script-based projects
const scriptProjects = await getProjectsBySource('script');

// Get only transcription-based projects
const transcribeProjects = await getProjectsBySource('transcribe');

// Get only URL-based projects
const urlProjects = await getProjectsBySource('url');
```

### 4. Get Projects from Specific Folder

Retrieve projects from a specific folder:

```python theme={null}
def get_folder_projects(folder_id, api_key):
    """
    Get all projects within a specific folder
    """
    url = f"https://api.pictory.ai/pictoryapis/v2/projects?folder={folder_id}"
    headers = {"Authorization": api_key}

    response = requests.get(url, headers=headers)
    data = response.json()

    return data['items']

# Example usage
folder_projects = get_folder_projects("your-folder-id", "YOUR_API_KEY")
print(f"Folder contains {len(folder_projects)} projects")
```

### 5. Find Recently Modified Projects

Get projects modified within the last N days:

```python theme={null}
from datetime import datetime, timedelta
import requests

def get_recent_projects(days=7, api_key="YOUR_API_KEY"):
    """
    Get projects modified in the last N days
    """
    url = "https://api.pictory.ai/pictoryapis/v2/projects"
    headers = {"Authorization": api_key}

    response = requests.get(url, headers=headers)
    data = response.json()

    # Calculate cutoff date
    cutoff = datetime.now() - timedelta(days=days)

    # Filter by saved date
    recent = [
        p for p in data['items']
        if datetime.fromisoformat(p['savedDate'].replace('Z', '+00:00')) > cutoff
    ]

    return recent

# Get projects from last 7 days
recent_projects = get_recent_projects(days=7)
print(f"Found {len(recent_projects)} projects modified in last 7 days")

for project in recent_projects:
    print(f"- {project['name']} (saved: {project['savedDate']})")
```

### 6. Organize Projects by Schema Version

Group projects by their schema version:

```javascript theme={null}
const organizeBySchemaVersion = async () => {
  const response = await fetch(
    'https://api.pictory.ai/pictoryapis/v2/projects',
    { headers: { 'Authorization': 'YOUR_API_KEY' } }
  );

  const data = await response.json();

  // Group by schema version
  const grouped = data.items.reduce((acc, project) => {
    const version = project.schemaVersion || 'legacy';
    if (!acc[version]) acc[version] = [];
    acc[version].push(project);
    return acc;
  }, {});

  // Display statistics
  Object.entries(grouped).forEach(([version, projects]) => {
    console.log(`${version}: ${projects.length} projects`);
  });

  return grouped;
};

// Organize projects
const projectsByVersion = await organizeBySchemaVersion();
```

### 7. Export Project Metadata

Export project metadata to CSV or JSON:

```python theme={null}
import json
import csv
import requests

def export_projects_json(api_key, filename="projects.json"):
    """
    Export all projects to JSON file
    """
    url = "https://api.pictory.ai/pictoryapis/v2/projects"
    headers = {"Authorization": api_key}

    response = requests.get(url, headers=headers)
    data = response.json()

    with open(filename, 'w') as f:
        json.dump(data['items'], f, indent=2)

    print(f"Exported {len(data['items'])} projects to {filename}")

def export_projects_csv(api_key, filename="projects.csv"):
    """
    Export all projects to CSV file
    """
    url = "https://api.pictory.ai/pictoryapis/v2/projects"
    headers = {"Authorization": api_key}

    response = requests.get(url, headers=headers)
    data = response.json()

    if not data['items']:
        print("No projects to export")
        return

    # Get fieldnames from first project
    fieldnames = ['id', 'name', 'source', 'savedDate', 'aspectRatio', 'schemaVersion', 'type']

    with open(filename, 'w', newline='') as f:
        writer = csv.DictWriter(f, fieldnames=fieldnames, extrasaction='ignore')
        writer.writeheader()
        writer.writerows(data['items'])

    print(f"Exported {len(data['items'])} projects to {filename}")

# Export to both formats
export_projects_json("YOUR_API_KEY")
export_projects_csv("YOUR_API_KEY")
```

### 8. Search Projects by Name

Search for projects by name pattern:

```python theme={null}
def search_projects_by_name(search_term, api_key):
    """
    Search for projects matching a name pattern
    """
    url = "https://api.pictory.ai/pictoryapis/v2/projects"
    headers = {"Authorization": api_key}

    response = requests.get(url, headers=headers)
    data = response.json()

    # Case-insensitive search
    matches = [
        p for p in data['items']
        if search_term.lower() in p['name'].lower()
    ]

    return matches

# Example usage
results = search_projects_by_name("hello", "YOUR_API_KEY")
print(f"Found {len(results)} projects containing 'hello':")
for project in results:
    print(f"- {project['name']} (ID: {project['id']})")
```