# Datasets Dataset management endpoints. ## List datasets > List datasets owned by the authenticated project. Optionally filter by container. ```json {"openapi":"3.1.0","info":{"title":"Maniac Inference Gateway API","version":"1.0.0"},"tags":[{"name":"Datasets","description":"Dataset management endpoints."}],"servers":[{"url":"https://platform.maniac.ai","description":"The Maniac API"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"API key in Authorization header using Bearer ."}},"schemas":{"ListResponse_Dataset_":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Object type identifier.","default":"list"},"data":{"items":{"$ref":"#/components/schemas/Dataset"},"type":"array","title":"Data","description":"Returned items."},"total":{"type":"integer","minimum":0,"title":"Total","description":"Total number of items available for this resource."}},"additionalProperties":false,"type":"object","required":["data","total"],"title":"ListResponse[Dataset]"},"Dataset":{"properties":{"id":{"type":"string","title":"Id","description":"Dataset id."},"object":{"type":"string","const":"dataset","title":"Object","description":"Object type.","default":"dataset"},"name":{"type":"string","title":"Name","description":"Dataset name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Dataset description."},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"Owner user id."},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id","description":"Project id."},"org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id","description":"Organization id."},"container_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Container Id","description":"Container id."},"requested_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Requested Size","description":"Requested dataset size."},"size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size","description":"Actual dataset size."},"filters":{"anyOf":[{"items":{"$ref":"#/components/schemas/DatasetFilter"},"type":"array"},{"type":"null"}],"title":"Filters","description":"Filters applied when building the dataset."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"Creation timestamp."},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Optional dataset tags."},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Arbitrary metadata."}},"type":"object","required":["id","name"],"title":"Dataset"},"DatasetFilter":{"properties":{"key":{"type":"string","title":"Key","description":"Filter key (e.g. 'model_name', 'status')."},"operator":{"$ref":"#/components/schemas/DatasetFilterOperator","description":"Filter operator."},"value":{"anyOf":[{},{"type":"null"}],"title":"Value","description":"Filter value (required for most operators)."}},"additionalProperties":false,"type":"object","required":["key","operator"],"title":"DatasetFilter"},"DatasetFilterOperator":{"type":"string","enum":["equals","not_equals","contains","not_contains","greater_than","less_than","greater_than_or_equal","less_than_or_equal","in","not_in","exists","not_exists","between"],"title":"DatasetFilterOperator"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ManiacError","description":"Error payload."}},"additionalProperties":false,"type":"object","required":["error"],"title":"ErrorResponse","description":"Response body for errors."},"ManiacError":{"properties":{"code":{"type":"string","title":"Code","description":"Machine-readable error code."},"message":{"type":"string","title":"Message","description":"Human-readable error message."},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details","description":"Additional error details."}},"additionalProperties":false,"type":"object","required":["code","message"],"title":"ManiacError","description":"Standard Maniac API error envelope.\n\nThis matches the shape already used by v2 auth (`detail={\"error\": {...}}`)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/datasets":{"get":{"tags":["Datasets"],"summary":"List datasets","description":"List datasets owned by the authenticated project. Optionally filter by container.","operationId":"datasets_list","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Max number of datasets.","default":100,"title":"Limit"},"description":"Max number of datasets."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Number of datasets to skip.","default":0,"title":"Offset"},"description":"Number of datasets to skip."},{"name":"container","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Container ID or label to filter datasets by.","title":"Container"},"description":"Container ID or label to filter datasets by."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListResponse_Dataset_"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Too Many Requests","headers":{"X-RateLimit-Limit":{"description":"Request limit per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the rate limit resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"501":{"description":"Not Implemented","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Upstream Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Create a dataset > Create a dataset for a container using telemetry filters. ```json {"openapi":"3.1.0","info":{"title":"Maniac Inference Gateway API","version":"1.0.0"},"tags":[{"name":"Datasets","description":"Dataset management endpoints."}],"servers":[{"url":"https://platform.maniac.ai","description":"The Maniac API"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"API key in Authorization header using Bearer ."}},"schemas":{"CreateDatasetReq":{"properties":{"name":{"type":"string","title":"Name","description":"Dataset name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Dataset description."},"container":{"type":"string","title":"Container","description":"Container id or label for source data."},"size":{"type":"integer","exclusiveMinimum":0,"title":"Size","description":"Requested dataset size."},"filters":{"items":{"$ref":"#/components/schemas/DatasetFilter"},"type":"array","title":"Filters","description":"Filter conditions."},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Optional dataset tags."},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Arbitrary metadata."}},"additionalProperties":false,"type":"object","required":["name","container","size"],"title":"CreateDatasetReq"},"DatasetFilter":{"properties":{"key":{"type":"string","title":"Key","description":"Filter key (e.g. 'model_name', 'status')."},"operator":{"$ref":"#/components/schemas/DatasetFilterOperator","description":"Filter operator."},"value":{"anyOf":[{},{"type":"null"}],"title":"Value","description":"Filter value (required for most operators)."}},"additionalProperties":false,"type":"object","required":["key","operator"],"title":"DatasetFilter"},"DatasetFilterOperator":{"type":"string","enum":["equals","not_equals","contains","not_contains","greater_than","less_than","greater_than_or_equal","less_than_or_equal","in","not_in","exists","not_exists","between"],"title":"DatasetFilterOperator"},"CreateDatasetRes":{"properties":{"id":{"type":"string","title":"Id","description":"ID of the created dataset."},"message":{"type":"string","title":"Message","description":"Status message."}},"type":"object","required":["id","message"],"title":"CreateDatasetRes"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ManiacError","description":"Error payload."}},"additionalProperties":false,"type":"object","required":["error"],"title":"ErrorResponse","description":"Response body for errors."},"ManiacError":{"properties":{"code":{"type":"string","title":"Code","description":"Machine-readable error code."},"message":{"type":"string","title":"Message","description":"Human-readable error message."},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details","description":"Additional error details."}},"additionalProperties":false,"type":"object","required":["code","message"],"title":"ManiacError","description":"Standard Maniac API error envelope.\n\nThis matches the shape already used by v2 auth (`detail={\"error\": {...}}`)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/datasets":{"post":{"tags":["Datasets"],"summary":"Create a dataset","description":"Create a dataset for a container using telemetry filters.","operationId":"datasets_create","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDatasetReq"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDatasetRes"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Too Many Requests","headers":{"X-RateLimit-Limit":{"description":"Request limit per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the rate limit resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"501":{"description":"Not Implemented","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Upstream Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Get a dataset > Fetch a dataset by id within the authenticated project. ```json {"openapi":"3.1.0","info":{"title":"Maniac Inference Gateway API","version":"1.0.0"},"tags":[{"name":"Datasets","description":"Dataset management endpoints."}],"servers":[{"url":"https://platform.maniac.ai","description":"The Maniac API"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"API key in Authorization header using Bearer ."}},"schemas":{"Dataset":{"properties":{"id":{"type":"string","title":"Id","description":"Dataset id."},"object":{"type":"string","const":"dataset","title":"Object","description":"Object type.","default":"dataset"},"name":{"type":"string","title":"Name","description":"Dataset name."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Dataset description."},"user_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Id","description":"Owner user id."},"project_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Project Id","description":"Project id."},"org_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Org Id","description":"Organization id."},"container_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Container Id","description":"Container id."},"requested_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Requested Size","description":"Requested dataset size."},"size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size","description":"Actual dataset size."},"filters":{"anyOf":[{"items":{"$ref":"#/components/schemas/DatasetFilter"},"type":"array"},{"type":"null"}],"title":"Filters","description":"Filters applied when building the dataset."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"Creation timestamp."},"tags":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Tags","description":"Optional dataset tags."},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata","description":"Arbitrary metadata."}},"type":"object","required":["id","name"],"title":"Dataset"},"DatasetFilter":{"properties":{"key":{"type":"string","title":"Key","description":"Filter key (e.g. 'model_name', 'status')."},"operator":{"$ref":"#/components/schemas/DatasetFilterOperator","description":"Filter operator."},"value":{"anyOf":[{},{"type":"null"}],"title":"Value","description":"Filter value (required for most operators)."}},"additionalProperties":false,"type":"object","required":["key","operator"],"title":"DatasetFilter"},"DatasetFilterOperator":{"type":"string","enum":["equals","not_equals","contains","not_contains","greater_than","less_than","greater_than_or_equal","less_than_or_equal","in","not_in","exists","not_exists","between"],"title":"DatasetFilterOperator"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ManiacError","description":"Error payload."}},"additionalProperties":false,"type":"object","required":["error"],"title":"ErrorResponse","description":"Response body for errors."},"ManiacError":{"properties":{"code":{"type":"string","title":"Code","description":"Machine-readable error code."},"message":{"type":"string","title":"Message","description":"Human-readable error message."},"details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Details","description":"Additional error details."}},"additionalProperties":false,"type":"object","required":["code","message"],"title":"ManiacError","description":"Standard Maniac API error envelope.\n\nThis matches the shape already used by v2 auth (`detail={\"error\": {...}}`)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/datasets/{dataset_id}":{"get":{"tags":["Datasets"],"summary":"Get a dataset","description":"Fetch a dataset by id within the authenticated project.","operationId":"datasets_retrieve","parameters":[{"name":"dataset_id","in":"path","required":true,"schema":{"type":"string","title":"Dataset Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dataset"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Too Many Requests","headers":{"X-RateLimit-Limit":{"description":"Request limit per window.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in current window.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when the rate limit resets.","schema":{"type":"integer"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"501":{"description":"Not Implemented","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Upstream Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.maniac.ai/api-reference/datasets.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.