---
category: [Administration & Integrations, Platform and Product Extensions, Platform and Product Extensions/Integration, Administration & Integrations/Custom Integrations & Apps]
keyword: [Integrate, Workday Integration, Orchestrate for Integrations, Orchestration, Orchestration Builder, Extend, API, Insight]
nav: wcp_docs
parent_url: /wcp_docs/
title: >- 
  Concept: Insights API
layout: subsection
---

The Orchestrate Insights REST API enables Extend customers to monitor, analyze, and troubleshoot orchestrations programmatically, rather than by manually examining the Developer Site Analytics dashboard.

You can find detailed information on their use in the REST API Explorer on the Workday Developer Site under `/reporting/v1`.

Some of the benefits of having programmatic access to orchestration runtime information:

-   Testing: Build custom Continuous Integation and Deployment pipelines to validate your deployed orchestrations' behavior in detail before promoting to production.
-   Automated Analytics: Create automated orchestration health reports and alerts.
-   Enhanced Troubleshooting: Access detailed run-level data for faster issue resolution.
-   ccount-Wide Visibility: Monitor orchestration performance across all apps and tenants in your account.


<b>Note:</b> Orchestration event data is retained for 29 days from execution. After this period, data is purged from the queryable dataset and historical data is not accessible from the API.

The Insights API provides data at 5 levels of granularity:

-   Organization Level: An overview of all applications in your organization across every tenant. Note that organization-level queries can take a relatively long time.
-   Tenant Level: An overview of all applications in a single tenant.
-   App Level: Aggregated metrics for all orchestrations within a single application.
-   Orchestration Level: Detailed run history and statistics for specific orchestrations.
-   Run Level: Execution details for individual orchestration runs, including process and step information.


Pagination is available for all Insights API responses.

<b>Endpoints and Access</b>

All Insights endpoints are under the `/reporting/v1` path.

<table><thead><tr><th>Level</th><th>Endpoint</th></tr></thead><tbody><tr><td>Organization</td><td><code>GET /reporting/v1.1/organizations/{orgId}/apps</code></td></tr><tr><td>Tenant</td><td><code>GET /reporting/v1.1/tenanted/apps</code></td></tr><tr><td>App</td><td><code>GET /reporting/v1.1/apps/{appId}/orchestrations</code></td></tr><tr><td>Orchestration</td><td><code>GET /reporting/v1.1/apps/{appId}/orchestrations/{orchName}/runs</code></td></tr><tr><td>Run</td><td><code>GET /reporting/v1.1/apps/{appId}/orchestrations/{orchName}/runs/{runId}</code></td></tr></tbody></table><br/>

Note that some endpoints require an additional Organizational UUID header in the format`wcp-org-uuid: {organization-uuid}`. For more information, consult the Developer Site REST API Explorer.

The authentication method you use to access Insights APIs depends on the level of granularity you're addressing, as this table summarizes.

<table><thead><tr><th>Level</th><th>Authentication Method</th></tr></thead><tbody><tr><td>Organization</td><td><p>Requires Devsite Developer Bearer Token (Octopaas token).</p> <p>Include this header in the <code>GET</code> request: <code>Authorization: Bearer {Devsite-access-token}</code>.</p> <p><b>Note:</b> Some endpoints require an additional header, <code>wcp-org-uuid: {organization-uuid}.</code></p> <p>Users must have appropriate Workday Devsite Developer privileges for the organization.</p></td></tr><tr><td>Tenant</td><td><p>Requires a Bearer token associated with a Workday Cloud Platform (WCP) API Client. Standard tenant ISU credentials or generic tenant tokens will NOT work.</p> <p>For more information, see:</p><ul><li><a href="/wcp_docs/GUID-cb3e0fcd-bb97-4005-8d10-3a02e88dab71-enHYPHENus.html">Concept: ISU Authentication</a>.
</li><li><a href="/wcp_docs/GUID-72d57df4-c4ec-4825-a6e8-fdd596cf930e.html">Assign Integration System Users to an App.</a>
</li></ul> Include this header in the <code>GET</code> request: <code>Authorization: Bearer {bearer-access-token}</code>.</td></tr><tr><td><ul><li>App
</li><li>Orchestration
</li><li>Run
</li></ul></td><td>Can use either the Devsite Developer Bearer Token or the Bearer token associated with a Workday Cloud Platform (WCP) API Client.</td></tr><tr><td> </td><td> </td></tr></tbody></table><br/>

<b>Apps Response Structure</b>

An apps-related response includes an array of apps. Each result in the array contains these elements:

-   `appId`: The Application ID.
-   `orchestrations`: An array of orchestration names.
-   `summaryState`: An object that provides state counts. Examples: `SUCCESS: 42`, `FAILED: 3`. Aggregates all runs across all orchestrations in the app.


<b>Orchestration Runs Response Structure</b>

A runs-related response includes `total`, a count of runs included after applying all filters, and an array of runs. Each result in the array contains these elements:

-   `runId`: The unique instance ID of this run.
-   `crid`: Common Request ID. A unique identifier for the request that initiated the orchestration run. Useful for tracing the origin of the orchestration run and correlating it with other related logs and requests across services.
-   `procIds`: An array of unique identifiers for each of the sequential processes within the orchestration run.
-   `startTime`: The run's start time in ISO 8601 format.
-   `tenantAlias`: The name of the tenant where the run was performed.
-   `computeDuration`: The run's duration in ISO 8601 format.
-   `state`: The run's current status. The possibilities are:

    -   RUNNING: The orchestration is currently in progress.
    -   AWAITING_CALLBACK: The orchestration is paused and waiting for an external callback to proceed.
    -   SUCCESS: The orchestration completed successfully.
    -   CANCELLED: The orchestration was cancelled before completion.
    -   COMPLETED_WITH_ERROR: The orchestration completed but encountered processing errors.
    -   QUEUED: The orchestration is queued and waiting to be executed.
    -   TIMED_OUT: The orchestration did not complete within the expected time frame.
    -   FAILED: The orchestration failed to complete successfully.
    -   FAILED_NOT_EXECUTED: The orchestration failed to launch.



<b>Run Details Response Structure</b>

An individual run-related response contains these elements:

-   `runId`: The orchestration runtime ID.
-   `elapsedDuration`: Time relapsed from start to end of run.
-   `computeDuration`: The sum of all process execution times.
-   `processes`: An array of values for `processId`, `stepsSuccessful`, and `stepsFailed`.


<b>Best Practices for Error Handling</b>

-   400 Errors (Bad Request): Review query parameters to ensure date ranges don't conflict and state values are valid.
-   403 Errors (Forbidden): Verify user has appropriate permissions for the organization or tenant.
-   429 Errors (Too Many Requests): Implement exponential backoff and respect rate limit headers.
-   Slow queries: Narrow the date range, add more specific filters, use pagination, or increase the duration of the timeout.


### Related Information

[Concept: ISU Authentication](/wcp_docs/GUID-cb3e0fcd-bb97-4005-8d10-3a02e88dab71-enHYPHENus.html)

[Create Integration System Users for Apps](/wcp_docs/GUID-3d6a3ac3-f03a-4ab6-bd9c-a8571eaaf5e0.html)

[Create Orchestration Credentials](/wcp_docs/uwh1613475703138.html)

[Concept: Extend App Security](/wcp_docs/vel1628698852360.html)