# Clips

## List clips

> Returns a cursor-paginated list of clips. Pass the \`nextCursor\` from the response back as \`cursor\` to fetch the next page.

```json
{"openapi":"3.0.0","info":{"title":"Patchwork Public API","version":"1.0"},"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Object":{"type":"object","properties":{}},"ClipCursorResultDto":{"type":"object","properties":{"items":{"description":"List of clips for this page","type":"array","items":{"$ref":"#/components/schemas/ClipResponseDto"}},"nextCursor":{"type":"string","nullable":true,"description":"Opaque cursor to pass as `cursor` in the next request. Absent when there are no more results."},"limit":{"type":"number","description":"Number of items per page"},"sortBy":{"type":"string","description":"Field used for sorting","enum":["createdDate","viewCount"]},"order":{"type":"string","description":"Sort direction","enum":["asc","desc"]}},"required":["items","limit","sortBy","order"]},"ClipResponseDto":{"type":"object","properties":{"_id":{"type":"string","description":"Clip document ID"},"username":{"type":"string","description":"Streamer username"},"clipId":{"type":"string","description":"Platform-specific clip ID"},"title":{"type":"string","description":"Clip title"},"duration":{"type":"number","description":"Clip duration in seconds"},"viewCount":{"type":"number","description":"Total view count"},"createdDate":{"format":"date-time","type":"string","description":"Date the clip was recorded"},"updatedDate":{"format":"date-time","type":"string","description":"Last updated date"},"thumbnailURL":{"type":"string","description":"Thumbnail image URL","nullable":true},"path":{"type":"string","description":"Path to the clip media file"},"source":{"type":"string","description":"Source platform","enum":["patchwork","twitch","kick"]},"sourceSlug":{"type":"string","description":"Platform-specific slug for the clip","nullable":true},"game":{"type":"string","description":"Game name","nullable":true},"stream":{"type":"string","description":"Stream document ID this clip belongs to","nullable":true}},"required":["_id","username","clipId","title","duration","viewCount","createdDate","updatedDate","thumbnailURL","path","source","sourceSlug","game","stream"]}}},"paths":{"/v1/clips":{"get":{"description":"Returns a cursor-paginated list of clips. Pass the `nextCursor` from the response back as `cursor` to fetch the next page.","operationId":"ClipsController_findMany","parameters":[{"name":"limit","required":false,"in":"query","description":"Number of clips to return per page. Min 1, max 100.","schema":{"$ref":"#/components/schemas/Object"}},{"name":"sortBy","required":false,"in":"query","description":"Field to sort by.","schema":{"default":"createdDate","type":"string","enum":["createdDate","viewCount"]}},{"name":"order","required":false,"in":"query","description":"Sort direction.","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"timeframe","required":false,"in":"query","description":"Relative time window to filter clips by creation date. Takes precedence over dateFrom/dateTo when both are provided.","schema":{"type":"string","enum":["24h","7d","30d","all"]}},{"name":"username","required":false,"in":"query","description":"Filter clips by streamer username (exact match, case-sensitive).","schema":{"type":"string"}},{"name":"streamer","required":false,"in":"query","description":"Alias for `username`.","schema":{"type":"string"}},{"name":"sources","required":false,"in":"query","description":"Filter by source platforms. Defaults to excluding \"patchwork\" clips when not specified.","schema":{"type":"array","items":{"type":"string","enum":["patchwork","twitch","kick"]}}},{"name":"q","required":false,"in":"query","description":"Case-insensitive title search.","schema":{"type":"string"}},{"name":"minViews","required":false,"in":"query","description":"Minimum view count filter (inclusive).","schema":{"minimum":0,"type":"number"}},{"name":"maxViews","required":false,"in":"query","description":"Maximum view count filter (inclusive). Must be greater than or equal to minViews if both are provided.","schema":{"minimum":0,"type":"number"}},{"name":"dateFrom","required":false,"in":"query","description":"Start of date range filter (ISO 8601). Filters on clip creation date.","schema":{"type":"string"}},{"name":"dateTo","required":false,"in":"query","description":"End of date range filter (ISO 8601). Filters on clip creation date.","schema":{"type":"string"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor from a previous response's `nextCursor` field. Do not modify this value.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated clip results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClipCursorResultDto"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Missing or invalid x-api-key header"}},"summary":"List clips","tags":["Clips"]}}}}
```