> ## Documentation Index > Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt > Use this file to discover all available pages before exploring further. # Start extraction > Start an extraction run over Files. It opens its own review workspace and returns it. **Operation ID:** `http.graph.extractions.start` ```http theme={null} POST /v1/orgs/{org}/projects/{project}/graph/extractions ``` ## OpenAPI ````yaml openapi.json POST /v1/orgs/{org}/projects/{project}/graph/extractions openapi: 3.1.0 info: title: Penumbra API version: v1 description: >- HTTP reference for Files, search, extraction, reviews, Graph, Shapes and sharing. servers: - url: https://api.pnbr.io description: Penumbra API security: [] paths: /v1/orgs/{org}/projects/{project}/graph/extractions: post: tags: - Extraction summary: Start extraction description: >- Start an extraction run over Files. It opens its own review workspace and returns it. Product guidance: [Extraction](/concepts/extraction). operationId: http.graph.extractions.start parameters: - name: org in: path required: true schema: type: string - name: project in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/http_graph_extractions_start_request' responses: 2XX: description: Success. content: application/json: schema: $ref: '#/components/schemas/http_graph_extractions_start_response' security: - bearerAuth: [] components: schemas: http_graph_extractions_start_request: oneOf: - type: object properties: file_ids: description: >- Native File UUIDs from list_files or search_files. Each File's current version and extracted text are pinned at admission; never a Workspace path. Give exactly one of file_ids or collection_id. minItems: 1 maxItems: 256 type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ collection_id: description: >- A Files collection to extract from, in place of file_ids. The collection's Files and their current versions are read once when the extraction starts; Files added or changed later are not part of this run. Give exactly one of file_ids or collection_id. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ idempotency_key: description: >- Caller-chosen key for this extraction. Repeating the same key replays the same admitted run instead of paying for a second one. type: string minLength: 1 maxLength: 200 level: description: >- How thorough: standard (items are double-checked before you review them) or fast (one read, no double-check). Omit for the project's default. type: string enum: - standard - fast - deep mode: type: string const: shape shape: description: >- The one published Shape name or id whose complete analytical perspective governs this operation. type: string minLength: 1 maxLength: 200 required: - idempotency_key - mode - shape additionalProperties: false - type: object properties: file_ids: description: >- Native File UUIDs from list_files or search_files. Each File's current version and extracted text are pinned at admission; never a Workspace path. Give exactly one of file_ids or collection_id. minItems: 1 maxItems: 256 type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ collection_id: description: >- A Files collection to extract from, in place of file_ids. The collection's Files and their current versions are read once when the extraction starts; Files added or changed later are not part of this run. Give exactly one of file_ids or collection_id. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ idempotency_key: description: >- Caller-chosen key for this extraction. Repeating the same key replays the same admitted run instead of paying for a second one. type: string minLength: 1 maxLength: 200 level: description: >- How thorough: standard (items are double-checked before you review them) or fast (one read, no double-check). Omit for the project's default. type: string enum: - standard - fast - deep mode: type: string const: typeset typeset: description: >- A perspective-neutral extraction aperture assembled from exact stable types. It does not import the broader analytical perspective of any containing Shape. type: object properties: name: type: string minLength: 1 maxLength: 256 description: type: string minLength: 1 maxLength: 2048 types: minItems: 1 maxItems: 512 type: array items: type: object properties: type_id: description: Stable project TypeId. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ alias: description: >- Request-local label for the model; it does not change semantic identity. type: string minLength: 1 maxLength: 128 required: - type_id additionalProperties: false relationship_ids: description: >- Exact stable RelationshipIds. Omit for every relationship whose endpoints are both selected; use [] for no relationships. maxItems: 512 type: array items: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - name - types additionalProperties: false required: - idempotency_key - mode - typeset additionalProperties: false http_graph_extractions_start_response: anyOf: - type: object properties: data: type: object properties: workspace: type: object properties: id: type: string creation_origin: type: string name: type: string description: anyOf: - type: string - type: 'null' status: type: string enum: - open - submitted - applied - closed revision: type: integer minimum: -9007199254740991 maximum: 9007199254740991 item_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 shape: anyOf: - type: object properties: shape_id: type: string artifact_digest: type: string required: - shape_id - artifact_digest additionalProperties: {} - type: 'null' bindings: type: array items: type: object properties: shape_id: type: string artifact_digest: type: string required: - shape_id - artifact_digest additionalProperties: {} bridge_set: anyOf: - type: object properties: digest: type: string declaration_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - digest - declaration_count additionalProperties: {} - type: 'null' created_at: type: string updated_at: type: string applied_at: anyOf: - type: string - type: 'null' replaced_by: type: string required: - id - creation_origin - name - description - status - revision - item_count - shape - bindings - bridge_set - created_at - updated_at - applied_at additionalProperties: {} run_id: type: string replayed: type: boolean expected_revision: type: integer minimum: -9007199254740991 maximum: 9007199254740991 execution_state: type: string shape: anyOf: - type: object properties: shape_id: type: string artifact_digest: type: string required: - shape_id - artifact_digest additionalProperties: {} - type: 'null' lens: type: object properties: kind: type: string lens_digest: type: string source_ontology_revision: type: string artifact_bindings: type: array items: type: object properties: shape_id: type: string artifact_digest: type: string required: - shape_id - artifact_digest additionalProperties: {} bridge_set_digest: type: string project_bridge_set_digest: type: string type_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 relationship_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - kind - lens_digest - source_ontology_revision - artifact_bindings - bridge_set_digest - project_bridge_set_digest - type_count - relationship_count additionalProperties: {} source_count: type: integer minimum: -9007199254740991 maximum: 9007199254740991 collection: anyOf: - type: object properties: id: type: string revision: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - id - revision additionalProperties: {} - type: 'null' level: anyOf: - type: string enum: - fast - standard - deep - type: 'null' estimate: anyOf: - type: object properties: schema: type: string const: penumbra.extraction-estimate version: type: number const: 1 expected_credit_micros: type: number high_credit_micros: type: number source_bytes: type: number calls: type: number billing: type: string const: elsewhere required: - schema - version - expected_credit_micros - high_credit_micros - source_bytes - calls additionalProperties: {} - type: 'null' required: - workspace - run_id - replayed - expected_revision - execution_state - shape - source_count - level - estimate additionalProperties: {} required: - data additionalProperties: false - type: object properties: request_id: type: string outcome: type: string const: pending reason: type: string operation: type: object properties: id: type: string request_id: type: string status_url: type: string required: - id - request_id - status_url additionalProperties: false approval: type: object properties: url: type: string status: type: string expires_at: type: string effects: type: array items: type: string next: type: string required: - url - status - expires_at - effects - next additionalProperties: false required: - request_id - outcome - reason - operation - approval additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.