Skip to main content
GET
/
api
/
v1
/
projects
List Projects
curl --request GET \
  --url https://app.nouvel.ai/api/v1/projects
{
  "projects": [
    {
      "id": "<string>",
      "title": "<string>",
      "description": {},
      "status": "<string>",
      "final_output_url": {},
      "aspect_ratio": {},
      "target_duration_seconds": {},
      "product_url": {},
      "created_at": "<string>",
      "updated_at": "<string>"
    }
  ],
  "pagination": {
    "page": 123,
    "limit": 123,
    "total": 123,
    "totalPages": 123,
    "hasMore": true
  }
}
Returns a paginated list of all video ad projects created by the authenticated user. Results are sorted by creation date (newest first) and can be filtered by project status.

​
Authentication

This endpoint requires a valid API key with the projects:read permission. 
Authorization: Bearer nvl_xxxx

​
Query Parameters

​
page
integer
default:1
Page number for pagination (1-indexed). Must be a positive integer.
​
limit
integer
default:20
Number of results to return per page. Must be between 1 and 100.
​
status
string
Filter projects by their current status. Omit to return all projects.Allowed values:
  • generating - Video scenes are being generated
  • post_processing - Generating voiceover and lip sync
  • stitching - Combining scenes with audio and captions
  • completed - Project is ready with final video
  • failed - Generation encountered an unrecoverable error
  • partial - Some scenes completed but project failed overall

​
Response

​
projects
array
List of project objects matching the query criteria.
​
pagination
object
Pagination metadata for navigating through results.

​
Example Requests

curl https://app.nouvel.ai/api/v1/projects \
  -H "Authorization: Bearer nvl_xxxx"

​
Example Response

{
  "projects": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Premium Collagen Ad - Vertical",
      "description": "A compelling 15-second ad showcasing the benefits of marine collagen supplement with professional spokesperson and product demo.",
      "status": "completed",
      "final_output_url": "https://storage.supabase.co/videos/final-550e8400.mp4",
      "aspect_ratio": "9:16",
      "target_duration_seconds": 15,
      "product_url": "https://example.com/products/collagen",
      "created_at": "2024-03-15T14:32:10.000Z",
      "updated_at": "2024-03-15T14:48:22.000Z"
    },
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "title": "Skincare Serum - Instagram",
      "description": null,
      "status": "generating",
      "final_output_url": null,
      "aspect_ratio": "9:16",
      "target_duration_seconds": 15,
      "product_url": "https://example.com/products/serum",
      "created_at": "2024-03-15T14:20:05.000Z",
      "updated_at": "2024-03-15T14:25:18.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3,
    "hasMore": true
  }
}

​
Notes

Security: Only projects belonging to the authenticated user are returned. API keys are scoped to individual user accounts.
Video Availability: The final_output_url is only populated when the project status is completed. For projects still in progress, this field will be null.
Sorting: Results are always sorted by created_at in descending order (newest projects first). Custom sorting is not currently supported.
Rate Limiting: This endpoint is rate-limited to 60 requests per minute per API key. See Rate Limits for details.