> ## Documentation Index > Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a dataset > Describe the dataset in a prompt, or send a spec from /v1/datasets/plan. The dataset starts filling in the background; poll GET /v1/datasets/{id} and stop once status is no longer populating: ready, empty (no rows landed), failed or cancelled, with `run.status` and `run.error` saying how the fill ended. Or follow the run at /runs/{runId}/events. ## OpenAPI ````yaml https://agent.tinyfish.ai/v1/openapi/datasets post /v1/datasets openapi: 3.0.0 info: title: TinyFish Datasets API version: 1.0.0 description: Describe a dataset in plain English and have agents fill it from the web. contact: name: TinyFish Support email: support@tinyfish.ai servers: - url: https://agent.tinyfish.ai security: [] paths: /v1/datasets: post: summary: Create a dataset description: >- Describe the dataset in a prompt, or send a spec from /v1/datasets/plan. The dataset starts filling in the background; poll GET /v1/datasets/{id} and stop once status is no longer populating: ready, empty (no rows landed), failed or cancelled, with `run.status` and `run.error` saying how the fill ended. Or follow the run at /runs/{runId}/events. operationId: createDataset requestBody: content: application/json: schema: type: object properties: prompt: type: string minLength: 3 maxLength: 15000 description: What the dataset should contain, in plain English example: >- Specialty coffee shops in Oakland with their website and rating spec: type: object properties: name: type: string minLength: 1 maxLength: 200 description: type: string minLength: 1 columns: type: array items: type: object properties: name: type: string minLength: 1 label: type: string minLength: 1 maxLength: 200 type: type: string enum: - string - number - boolean - url - date is_primary_key: type: boolean retrieval_hint: type: string maxLength: 2000 required: - name - type - is_primary_key minItems: 1 maxItems: 64 keep_when: type: object properties: column: type: string minLength: 1 required: - column required: - name - description - columns description: >- A schema to use as is, such as one returned by POST /v1/datasets/plan target_rows: type: integer minimum: 1 maximum: 250 description: Rows to fill the dataset to, 1 to 250 example: 100 populate: type: boolean default: true description: Start filling the dataset right away additionalProperties: false description: Exactly one of prompt or spec responses: '201': description: Dataset created, not populating content: application/json: schema: $ref: '#/components/schemas/Dataset' '202': description: Dataset created and populating content: application/json: schema: $ref: '#/components/schemas/Dataset' '400': description: Invalid request content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - VAULT_RECONNECT_REQUIRED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - FREE_ALLOWANCE_EXHAUSTED - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '401': description: Unauthorized - missing or invalid API key content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - VAULT_RECONNECT_REQUIRED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - FREE_ALLOWANCE_EXHAUSTED - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '403': description: Forbidden - team API keys cannot use Datasets content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - VAULT_RECONNECT_REQUIRED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - FREE_ALLOWANCE_EXHAUSTED - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '404': description: Not found - the dataset or run, or the Datasets API for this account content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - VAULT_RECONNECT_REQUIRED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - FREE_ALLOWANCE_EXHAUSTED - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '422': description: The agent could not design a schema for the prompt content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - VAULT_RECONNECT_REQUIRED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - FREE_ALLOWANCE_EXHAUSTED - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '429': description: Rate limit or daily run limit exceeded headers: Retry-After: description: Seconds to wait before retrying. schema: type: string content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - VAULT_RECONNECT_REQUIRED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - FREE_ALLOWANCE_EXHAUSTED - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '500': description: Internal server error content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - VAULT_RECONNECT_REQUIRED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - FREE_ALLOWANCE_EXHAUSTED - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '502': description: Datasets service gave a bad answer; retry content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - VAULT_RECONNECT_REQUIRED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - FREE_ALLOWANCE_EXHAUSTED - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '503': description: Datasets service unavailable; retry content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - VAULT_RECONNECT_REQUIRED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - FREE_ALLOWANCE_EXHAUSTED - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format '504': description: Planning the schema timed out content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - MISSING_API_KEY - INVALID_API_KEY - INVALID_INPUT - RATE_LIMIT_EXCEEDED - DAILY_LIMIT_EXCEEDED - INTERNAL_ERROR - RETRY_REQUIRED - UNAUTHORIZED - VAULT_RECONNECT_REQUIRED - FORBIDDEN - NOT_FOUND - FEATURE_NOT_AVAILABLE - SERVICE_BUSY - TIMEOUT - INSUFFICIENT_CREDITS - FREE_ALLOWANCE_EXHAUSTED - CONTENT_POLICY_VIOLATION - MAX_STEPS_EXCEEDED - SITE_BLOCKED - TASK_FAILED - CANCELLED description: Machine-readable error code example: INVALID_INPUT message: type: string description: Human-readable error message example: Field "url" is required and must be a string details: nullable: true description: Additional error details (validation errors, etc.) required: - code - message request_id: type: string description: >- Request correlation ID, also returned as the X-Request-ID response header. Include it when reporting issues. example: 8f9dba20-e37b-4749-a919-2269e28b4a2c required: - error description: Standard error response format security: - ApiKeyAuth: [] components: schemas: Dataset: type: object properties: id: type: string format: uuid name: type: string spec: type: object properties: name: type: string minLength: 1 maxLength: 200 description: type: string minLength: 1 columns: type: array items: type: object properties: name: type: string minLength: 1 label: type: string minLength: 1 maxLength: 200 type: type: string enum: - string - number - boolean - url - date is_primary_key: type: boolean retrieval_hint: type: string maxLength: 2000 required: - name - type - is_primary_key minItems: 1 maxItems: 64 keep_when: type: object properties: column: type: string minLength: 1 required: - column required: - name - description - columns status: type: string enum: - empty - populating - ready - failed - cancelled description: >- empty: no rows yet; populating: a run is adding rows; ready: rows stand; failed or cancelled: how the latest run ended target_rows: type: integer description: Rows a populate fills to row_count: type: integer run: type: object nullable: true properties: id: type: string format: uuid status: type: string enum: - queued - running - done - cancelled - failed started_at: type: string format: date-time finished_at: type: string format: date-time error: type: string description: Why the run failed required: - id - status - started_at description: The latest run, however it ended; null when the dataset never ran created_at: type: string format: date-time required: - id - name - spec - status - target_rows - row_count - run - created_at description: A dataset and the state of its rows securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication. Get your key from the API Keys page. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.