> For the complete documentation index, see [llms.txt](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/activitylog/extractionruns.md).

# Extraction Runs

List recent policy extraction runs with detailed per-step processing metrics

The Extraction Runs API returns the recent extraction runs for a single policy, each with detailed per-step metrics describing how the policy processed that extraction. It backs the run-level detail shown on the [Provisioning Activity](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/getting-started/activity-log.md) page, complementing the per-task counts from the [Provisioning Status API](/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/activitylog/provisioningstats.md).

**Extraction Runs API** helps you:

* Review the recent processing history for a policy, most recent first
* Inspect how each run progressed through identity detection, validation, workflow filtering, and task processing
* Troubleshoot runs that were blocked, skipped, or errored

## Endpoints

| Method | Endpoint                                      | Description                                  |
| ------ | --------------------------------------------- | -------------------------------------------- |
| GET    | [List Extraction Runs](#list-extraction-runs) | Retrieve recent extraction runs for a policy |

## Key Concepts

### Processing steps

Each run reports an `operational_status` (`RUNNING` or `COMPLETED`), the `extraction_event_id`, `started_at`/`completed_at` timestamps, and up to four processing steps. Every step carries its own `status` (`WAITING`, `PROCESSING`, `SUCCESS`, or `FAILED`):

| Step                       | Description                                                                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `identity_detection_step`  | Counts of new, updated, deleted, unchanged, and prior identities detected from the source                                      |
| `identity_validation_step` | Valid vs. invalid identity counts; only populated when identity validation is enabled. Includes whether processing was blocked |
| `workflow_filtering_step`  | How identities were filtered down to tasks per workflow, including disabled/skipped workflows and per-workflow statistics      |
| `task_processing_step`     | Task counts by state (total, completed, in-progress, pending, errored, skipped, abandoned, retried), overall and per workflow  |

## List Extraction Runs

### Endpoint

```sh
GET /api/private/lifecycle_management/policy_extraction_runs/{policy_id}
```

### Description

Retrieve the recent extraction runs for the policy identified by the required `policy_id` path parameter. Results are ordered by `started_at` descending and support pagination with `page_size` and `page_token`. Filtering and custom ordering are not currently supported.

### API Reference

{% openapi src="/files/Aco9gj4MY2XoNiD4zIjr" path="/api/private/lifecycle\_management/policy\_extraction\_runs/{policy\_id}" method="get" %}
[openapi.yaml](https://1967633068-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MZDkWMxox3pekd0NsZJ%2Fuploads%2Fgit-blob-36dc6f3613465aa5618f4e7c3e32d08da0b9b3c7%2Fopenapi.yaml?alt=media)
{% endopenapi %}

### Request Example

```bash
curl -X GET "https://your-tenant.vezacloud.com/api/private/lifecycle_management/policy_extraction_runs/policy-abc-123?page_size=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

## Authentication

All Extraction Runs API requests require authentication. See [API Authentication](/4yItIzMvkpAvMVFAamTf/developers/api/authentication.md) for details.

## Related Documentation

* [Provisioning Activity](/4yItIzMvkpAvMVFAamTf/features/lifecycle-management/getting-started/activity-log.md)
* [Provisioning Status](/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/activitylog/provisioningstats.md)
* [Extraction Events](/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/activitylog/extractionevents.md)
* [Triggered Workflows](/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/activitylog/triggeredworkflows.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.veza.com/4yItIzMvkpAvMVFAamTf/developers/api/lifecycle-management/activitylog/extractionruns.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.