> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdecisional.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Tool Run

> Creates a new tool run to extract fields from data sources

## Extract Fields from Data Sources

The Extract Fields tool allows you to automatically extract structured information from documents in your knowledge engine. This is useful for:

* Pulling specific data points from contracts, invoices, or reports
* Extracting consistent information across multiple documents
* Converting unstructured document data into structured format

The tool uses AI to identify and extract the specific fields you define, with confidence scores for each extraction.

### Request

<ParamField body="tool" type="object" required>
  Configuration for the extraction tool

  <Expandable title="Tool Properties">
    <ParamField body="type" type="string" required>
      Type of tool to run. Currently supports `extract_fields_from_data_sources`
    </ParamField>

    <ParamField body="model" type="string" required>
      The AI model to use for extraction. Currently supports `gemini-1.5-pro`
    </ParamField>

    <ParamField body="knowledge_engine_id" type="string" required>
      ID of the knowledge engine containing the data sources
    </ParamField>

    <ParamField body="tagged_data_sources" type="array" required>
      List of data sources to extract fields from

      <Expandable title="Data Source Properties">
        <ParamField body="id" type="string" required>
          ID of the data source
        </ParamField>

        <ParamField body="page_range" type="string">
          Range of pages to analyze (e.g., "1-5")
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="fields" type="array" required>
      List of fields to extract

      <Expandable title="Field Properties">
        <ParamField body="field_name" type="string" required>
          Name identifier for the field
        </ParamField>

        <ParamField body="description" type="string" required>
          Description of what the field represents
        </ParamField>

        <ParamField body="type" type="string" required>
          Type of data to extract. Supported types:

          * `text` - Generic text
          * `id_alphanumeric` - Alphanumeric identifiers
          * `verbatim` - Exact text passages
          * `number` - Numeric values
          * `percentage` - Percentage values
          * `currency` - Monetary amounts
          * `currency_symbol` - Currency codes
          * `date` - Date values
          * `single_select` - Single selection from options
          * `multi_select` - Multiple selections from options
          * `url` - Website URLs
        </ParamField>

        <ParamField body="options" type="array">
          Required for `single_select` and `multi_select` types. List of possible values.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="include_confidence_scores" type="boolean">
      Whether to include confidence scores for each extraction (default: true)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="stream_response" type="boolean">
  Whether to stream the response (default: false)
</ParamField>

<ParamField body="async_response" type="boolean">
  Whether to process the request asynchronously (default: false)
</ParamField>

<ParamField body="notes" type="object">
  Custom metadata for the tool run
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique identifier for the tool run
</ResponseField>

<ResponseField name="status" type="string">
  Status of the tool run. Possible values: `queued`, `processing`, `completed`, `failed`
</ResponseField>

<ResponseField name="created_at" type="integer">
  Unix timestamp when the tool run was created
</ResponseField>

<ResponseField name="tool" type="object">
  The tool configuration used for this run (same as request)
</ResponseField>

<ResponseField name="result" type="object">
  Results of the extraction

  <Expandable title="Result Properties">
    <ResponseField name="extracted_fields" type="object">
      Object containing all extracted fields

      <Expandable title="Extracted Field Format">
        <ResponseField name="[field_name]" type="object">
          For each field defined in the request

          <ResponseField name="value" type="any">
            The extracted value
          </ResponseField>

          <ResponseField name="type" type="string">
            The type of the extracted field
          </ResponseField>

          <ResponseField name="confidence" type="number">
            Confidence score (0-1) for the extraction
          </ResponseField>

          <ResponseField name="options" type="array">
            For `single_select` and `multi_select` types, the available options
          </ResponseField>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Processing metadata for the extraction

      <ResponseField name="processing_time" type="number">
        Processing time in milliseconds
      </ResponseField>

      <ResponseField name="sources_analyzed" type="number">
        Number of data sources analyzed
      </ResponseField>

      <ResponseField name="fields_extracted" type="number">
        Number of fields successfully extracted
      </ResponseField>

      <ResponseField name="average_confidence" type="number">
        Average confidence score across all extractions
      </ResponseField>
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

### Request Example

```json theme={null}
{
  "tool": {
    "type": "extract_fields_from_data_sources",
    "model": "gemini-1.5-pro",
    "knowledge_engine_id": "kng_abc123def456",
    "tagged_data_sources": [
      {
        "id": "dsc_abc123asdhas",
        "page_range": "1-5"
      },
      {
        "id": "dsc_def456qwerty",
        "page_range": "7-9"
      }
    ],
    "fields": [
      {
        "field_name": "customer_full_name",
        "description": "The full name of the customer as it appears on the document",
        "type": "text"
      },
      {
        "field_name": "contract_id",
        "description": "The unique alphanumeric identifier of the contract",
        "type": "id_alphanumeric"
      },
      {
        "field_name": "exact_statement",
        "description": "The exact statement of work as written in the document",
        "type": "verbatim"
      },
      {
        "field_name": "quantity_ordered",
        "description": "The number of items ordered",
        "type": "number"
      },
      {
        "field_name": "discount_rate",
        "description": "The percentage discount applied to the order",
        "type": "percentage"
      },
      {
        "field_name": "total_amount",
        "description": "The total amount to be paid",
        "type": "currency"
      },
      {
        "field_name": "currency_code",
        "description": "The currency symbol used in the transaction",
        "type": "currency_symbol"
      },
      {
        "field_name": "delivery_date",
        "description": "The date when the items will be delivered",
        "type": "date"
      },
      {
        "field_name": "payment_method",
        "description": "The method of payment selected by the customer",
        "type": "single_select",
        "options": ["Credit Card", "Wire Transfer", "ACH", "Check", "PayPal"]
      },
      {
        "field_name": "applicable_taxes",
        "description": "All types of taxes applied to this transaction",
        "type": "multi_select",
        "options": ["State Sales Tax", "Federal Excise Tax", "VAT", "Environmental Fee", "Import Duty", "Luxury Tax"]
      },
      {
        "field_name": "company_website",
        "description": "The URL of the company's website",
        "type": "url"
      }
    ]
  },
  "stream_response": false,
  "async_response": true,
  "notes": {
    "custom_field": "value",
    "priority": "high"
  }
}
```

### Response Example

```json theme={null}
{
  "id": "trun_ab7321xyw890",
  "status": "completed",
  "created_at": 1705487200,
  "tool": {
    "type": "extract_fields_from_data_sources",
    "model": "gemini-1.5-pro",
    "knowledge_engine_id": "kng_abc123def456",
    "tagged_data_sources": [
      {
        "id": "dsc_abc123asdhas",
        "page_range": "1-5"
      },
      {
        "id": "dsc_def456qwerty",
        "page_range": "7-9"
      }
    ],
    "fields": [
      {
        "field_name": "customer_full_name",
        "description": "The full name of the customer as it appears on the document",
        "type": "text"
      },
      {
        "field_name": "contract_id",
        "description": "The unique alphanumeric identifier of the contract",
        "type": "id_alphanumeric"
      },
      {
        "field_name": "exact_statement",
        "description": "The exact statement of work as written in the document",
        "type": "verbatim"
      },
      {
        "field_name": "quantity_ordered",
        "description": "The number of items ordered",
        "type": "number"
      },
      {
        "field_name": "discount_rate",
        "description": "The percentage discount applied to the order",
        "type": "percentage"
      },
      {
        "field_name": "total_amount",
        "description": "The total amount to be paid",
        "type": "currency"
      },
      {
        "field_name": "currency_code",
        "description": "The currency symbol used in the transaction",
        "type": "currency_symbol"
      },
      {
        "field_name": "delivery_date",
        "description": "The date when the items will be delivered",
        "type": "date"
      },
      {
        "field_name": "payment_method",
        "description": "The method of payment selected by the customer",
        "type": "single_select",
        "options": ["Credit Card", "Wire Transfer", "ACH", "Check", "PayPal"]
      },
      {
        "field_name": "applicable_taxes",
        "description": "All types of taxes applied to this transaction",
        "type": "multi_select",
        "options": ["State Sales Tax", "Federal Excise Tax", "VAT", "Environmental Fee", "Import Duty", "Luxury Tax"]
      },
      {
        "field_name": "company_website",
        "description": "The URL of the company's website",
        "type": "url"
      }
    ],
    "include_confidence_scores": true,
    "stream_response": false,
    "async_response": true,
    "notes": {
      "custom_field": "value",
      "priority": "high"
    }
  },
  "result": {
    "extracted_fields": {
      "customer_full_name": {
        "value": "Jonathan Michael Rodriguez",
        "type": "text",
        "confidence": 0.96
      },
      "contract_id": {
        "value": "CTR-2025-XZ793",
        "type": "id_alphanumeric",
        "confidence": 0.99
      },
      "exact_statement": {
        "value": "Client agrees to pay all invoices within 30 days of receipt and acknowledges late payments are subject to a 2.5% monthly fee.",
        "type": "verbatim",
        "confidence": 0.97
      },
      "quantity_ordered": {
        "value": 375,
        "type": "number",
        "confidence": 0.98
      },
      "discount_rate": {
        "value": 15.5,
        "type": "percentage",
        "confidence": 0.93
      },
      "total_amount": {
        "value": 15782.50,
        "type": "currency",
        "confidence": 0.99
      },
      "currency_code": {
        "value": "USD",
        "type": "currency_symbol",
        "confidence": 0.99
      },
      "delivery_date": {
        "value": "2025-04-15",
        "type": "date",
        "confidence": 0.95
      },
      "payment_method": {
        "value": "Wire Transfer",
        "type": "single_select",
        "options": ["Credit Card", "Wire Transfer", "ACH", "Check", "PayPal"],
        "confidence": 0.92
      },
      "applicable_taxes": {
        "value": ["State Sales Tax", "Environmental Fee", "Import Duty"],
        "type": "multi_select",
        "options": ["State Sales Tax", "Federal Excise Tax", "VAT", "Environmental Fee", "Import Duty", "Luxury Tax"],
        "confidence": 0.91
      },
      "company_website": {
        "value": "https://www.acmetechnologies.com",
        "type": "url",
        "confidence": 0.97
      }
    },
    "metadata": {
      "processing_time": 2350,
      "sources_analyzed": 2,
      "fields_extracted": 11,
      "average_confidence": 0.96
    }
  }
}
```