---
title: "Extract skills with source tracing"
method: POST
path: "/versions/{version}/extract/trace"
tags: ["Extract"]
---

# Extract skills with source tracing

`POST /versions/{version}/extract/trace`

Returns a list of skills found in a document with its trace information, including contextual classification data found in the document that resulted in a skill match, and optionally the normalized text from the document used to extract skills.

Supported document types and their expected Content-Type:
  * JSON – `application/json` **Document must be UTF-8 encoded.**
  * Plain text – `text/plain`
  * PDF – `application/pdf`
  * Word (docx) – `application/vnd.openxmlformats-officedocument.wordprocessingml.document`

> For the most accurate results mapping `sourceStart` and `sourceEnd` byte offsets on surface forms and context forms, be sure to request `includeNormalizedText` as `true`. Byte offsets are guaranteed to match the text returned in the `normalizedText` field.
>
> Note that these are byte offsets, be sure the language you are parsing this text in is representing the returned string's characters as 8-bit bytes for proper source offset referencing.

Request document size is limited to 10MB, text parsed from the document is limited to 50KB.

Note that this endpoint has a free tier monthly quota of 50 requests. [Contact us](https://skills.emsidata.com/contact) if you'd like this increased or made unlimited. Responses from this endpoint will include two headers, `RateLimit-Remaining` and `RateLimit-Reset`, which indicate how many requests you have remaining in your current quota period and when that quota will reset, respectively.

## Path parameters

- `version` string, required

## Query parameters

- `language` string
- `includeNormalizedText` boolean

## Request body

- object
  - `text` string, required
  - `includeNormalizedText` boolean
  - `confidenceThreshold` number

## Response `200`

OK

- object
  - `attributions` object[], required
    - `name` string, required
    - `text` string, required
  - `data` object, required
    - `trace` object[], required
      - `classificationData` object, required
        - `contextForms` object[], required — Provides information about context words that aided skill classifications
          - `sourceStart` integer, required
          - `sourceEnd` integer, required
          - `value` string, required
        - `skills` object[], required
          - `confidence` number, required
          - `skill` object, required
            - `type` object, required
              - …
            - `id` string, required
            - `name` string, required
            - `tags` object[], required
              - …
            - `infoUrl` string, required
            - `description` string, nullable
            - `descriptionSource` string, nullable
      - `surfaceForm` object, required — Provides information about the original word that is classified as a skill
        - `sourceStart` integer, required
        - `sourceEnd` integer, required
        - `value` string, required
    - `skills` object[], required
      - `confidence` number, required
      - `skill` object, required
        - `type` object, required
          - `id` string, required
          - `name` string, required
        - `id` string, required
        - `name` string, required
        - `tags` object[], required
          - `key` string, required
          - `value` string, required
        - `infoUrl` string, required
        - `description` string, nullable
        - `descriptionSource` string, nullable
    - `normalizedText` string, nullable, required — Surface form and context form trace offsets are guaranteed to match this document. If the `includeNormalizedText` param is not specified or is `false` this will be `null`.

## Other responses

- `400` — bad request
- `404` — requested resource not found
- `413` — request size too large
- `415` — wrong content type for request body

---

[API](https://skmtc.net/lightcast/apis/alumni-pathways-2-0.md) · [All operations](https://skmtc.net/lightcast/apis/alumni-pathways-2-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lightcast/alumni-pathways-2-0/revisions/fc66b9877391/schema)