Skip to content
KiweelyKiweelyKiweely

Querying the Workday Worker Directory, Supervisory Hierarchy, and Cost Centers with WQL

Use Workday Query Language (WQL) against indexedAllWorkers or workersForHCMReporting to query worker business titles, managers, supervisory organizations, locations, and cost centers in a single HTTP request while enforcing the caller’s contextual Workday domain security.

  • Checked against Workday on
  • Applies to Workday WQL & Reporting
  • 6 min read
  • Published
  • By Kiweely
On this page

To query the Workday worker directory, reporting chain, supervisory hierarchy, and cost centers without pulling bloated SOAP Get_Workers XML payloads, send a Workday Query Language (WQL) request to the /wql/v1 REST service using an indexed or Worker-based data source such as indexedAllWorkers or workersForHCMReporting. A single SELECT statement returns one row per worker with exact JSON descriptors and Workday IDs (WID) while honoring the caller’s Workday domain and row-level security.

Choosing the wrong worker data source is the number-one cause of slow WQL responses, missing effective-dated attributes on future hires, or unexpected terminated rows appearing in directory searches.

Choosing the Right Worker Data Source in WQL

Before writing a query, verify data source metadata in your tenant via GET /dataSources?SourceIndexType=Indexed or GET /dataSources/{ID}. These five Workday-delivered Worker data sources serve distinct directory and org-chart jobs:

Data Source Alias Descriptor Row Population & Effective-Date Behavior Best Use Case
Data Source AliasindexedAllWorkers DescriptorIndexed All Workers Row Population & Effective-Date BehaviorActive workers and workers with a future hire/contract date; backed by Workday’s search index for sub-second filtering. Best Use CaseLive employee directory search, org chart lookup, and autocomplete UIs.
Data Source AliasworkersForHCMReporting DescriptorWorkers for HCM Reporting Row Population & Effective-Date BehaviorActive and terminated workers (1 row per worker). Active workers report as of today; terminated workers report as of their last day of work. Best Use CaseGeneral HCM directory + cost center reporting when workerActive = true is filtered.
Data Source AliasallActiveAndTerminatedWorkers DescriptorAll Active and Terminated Workers Row Population & Effective-Date BehaviorActive and terminated workers; supports Effective Date parameter (supportsEffectiveDate: true) for active workers. Best Use CasePoint-in-time directory snapshots as of a specific effective date.
Data Source AliasmyDirectAndIndirectWorkers DescriptorMy Direct and Indirect Workers Row Population & Effective-Date BehaviorActive workers rolling up to the currently signed-in user only; excludes terminated workers automatically. Best Use CaseManager self-service org-chart and team directory views.
Data Source AliasallWorkers DescriptorAll Workers Row Population & Effective-Date BehaviorActive, terminated, and future hires (supportsEffectiveDate: true). Returns blank position fields if effective date precedes hire date. Best Use CaseCross-population audits including pre-start future hires.

Core WQL Field Aliases for Directory, Org Hierarchy, and Cost Centers

Always verify field aliases in your tenant via GET /dataSources/{ID}/fields (or the View WQL Alias action in Workday), because report fields vary slightly by enabled functional areas. On indexedAllWorkers, workersForHCMReporting, and allActiveAndTerminatedWorkers, these delivered aliases cover 95% of directory and org-structure queries:

  • Worker Identity & Contact: worker, nameInReportingDisplayFormat, legalName_FirstName, legalName_LastName, businessTitle, jobProfilePrimary, position, positionID, email_PrimaryWorkOrPrimaryHome, phoneNumbers, workerType_Text, employeeType, workerActive, activeStatus, onLeave.
  • Location: location, location_Name, primaryAddress_CountryName.
  • Reporting Chain & Management Levels: workersManager, managementLevel, and flattened management chain levels manager_Level01 (CEO / top level) through manager_Level10.
  • Supervisory Hierarchy: supervisoryOrganization, supervisoryOrganization_Superior, supervisoryOrganizationTop, supervisoryOrganization_Hierarchy, supervisoryOrganization_OrganizationTop_GtOrganization, supervisoryOrganization_PrimaryLocation.
  • Cost Center & Worktags: costCenters, costCenter_Name, costCenter_Manager, costCenter_OrganizationTop, costCenter_OrganizationSubtype, organizationAssignments.

Concrete WQL Query Patterns

Workday supports WQL over tenanted hosts (https://{hostname}/ccx/api/wql/v1/{tenant}/data) and the Workday Cloud Platform API Gateway (https://api.workday.com/wql/v1/data).

1. Active Worker Directory Search by Location or Name

Filter workersForHCMReporting (or indexedAllWorkers) to active employees, returning business title, primary work email, direct manager, supervisory organization, and cost center:

sql
SELECT worker,
       nameInReportingDisplayFormat,
       businessTitle,
       email_PrimaryWorkOrPrimaryHome,
       workersManager,
       supervisoryOrganization,
       location,
       costCenter_Name,
       costCenter_Manager
FROM workersForHCMReporting
WHERE workerActive = true
  AND location_Name = 'Chicago'
ORDER BY legalName_LastName ASC
LIMIT 100 OFFSET 0

Cache Tip: Workday caches GET /data WQL results for 30 minutes. Including offset=0 as a URL query parameter (/data?offset=0&query=...) forces Workday to bypass the 30-minute cache and return live post-transaction state.

When a lookup field on Worker points to a Related Business Object (RBO)—such as supervisoryOrganization, workersManager, or costCenters—use curly-brace {} notation in SELECT to pull attributes directly from the related object without a second HTTP round-trip. When filtering on an RBO attribute, use WHERE ON and omit the curly braces:

sql
SELECT worker,
       businessTitle,
       workersManager{businessTitle, email_PrimaryWorkOrPrimaryHome} AS managerDetails,
       supervisoryOrganization,
       supervisoryOrganization_Superior,
       costCenters
FROM indexedAllWorkers
WHERE workerActive = true

Keep two strict WQL RBO rules in mind:

  1. 500-Instance Limit on Multi-Instance RBOs: If a multi-instance lookup field on a single row returns more than 500 related instances, WQL throws a runtime error. Query a data source anchored on that child business object instead.
  2. No {} Inside GROUP BY: You cannot select {} RBO sub-fields in a query that contains a GROUP BY clause, and third-party HTTP clients must URL-encode { (%7B) and } (%7D) when calling GET /data. For queries between 2,048 and 16,000 characters—or to avoid URL-encoding curly braces—send POST /data:
json
{
  "query": "SELECT worker, businessTitle, workersManager, supervisoryOrganization, supervisoryOrganization_OrganizationTop_GtOrganization, costCenter_Name FROM indexedAllWorkers WHERE workerActive = true LIMIT 50"
}

3. Rolling Up Headcount by Supervisory Organization and Cost Center

To summarize active worker counts across supervisory organizations or cost centers for an org-chart overview, use GROUP BY on top-level single-instance fields:

sql
SELECT supervisoryOrganization,
       costCenter_Name,
       count(worker) AS workerCount
FROM workersForHCMReporting
WHERE workerActive = true
GROUP BY supervisoryOrganization, costCenter_Name

Security Domains Required to Execute Directory WQL Queries

Even though workersForHCMReporting and indexedAllWorkers state in their metadata that they access workers “regardless of contextual security” at the data-source row level, Workday still enforces domain security on both the WQL service and every individual report field in your SELECT and WHERE clauses:

  1. WQL Execution Access: The caller’s security group must hold Get / View permission on the Workday Query Language (System / Core Reporting) domain and the API client must include the corresponding Functional Area scopes.
  2. Public Directory vs. Restricted Worker Fields:
    • Standard directory fields (worker, businessTitle, supervisoryOrganization, workersManager, location, public work email_PrimaryWorkOrPrimaryHome) are typically governed by Person Data: Public Worker Reports and Worker Data: Public Worker Reports (similar to the Search: Find Worker domain backing the Find Workers report).
    • Organization Visibility overrides (Visibility on Create Supervisory Organization) hide restricted supervisory organizations even from callers with broad role-based security.
    • Multiple-job nuance: just as Workday’s Find Workers facets suppress primary-only facets on multi-job workers unless scoped to jobProfilePrimary or position, always verify whether your workforce holds multiple concurrent positions (indexedPositionsAndJobs_AllStaffingModels) before assuming a 1:1 worker-to-cost-center mapping.

To check which domain secures any WQL field in your tenant, search for the underlying report field in Workday, open Related Actions -> Security -> View Security, and confirm your target security group holds view rights.

Verification Checklist Before Shipping a Directory Query

  • Test with Non-Admin Security: Never validate a WQL query solely as an unconstrained System Administrator or ISU; test under an ordinary Employee As Self or Manager OAuth grant to verify no field throws a permission error.
  • Paginate Explicitly: Always pass limit and offset when a supervisory subtree can exceed default page sizes.
  • Filter workerActive = true: Both allWorkers and workersForHCMReporting include terminated workers by default; omitting workerActive = true pollutes live org charts with historical leavers.

If you are prototyping and validating tenant-specific WQL aliases while building reports or Extend apps, Kiweely Vine inspects your tenant’s live WQL data sources and tests queries on Mac and Windows (Vine Free is free for your Workday personal developer account and its tenant. Any other tenant needs Vine Personal at $99 a month for one person, or a Vine Team seat at $149 a month.). And to let every employee search live org charts and cost centers in Claude, ChatGPT, or Gemini under their own Workday OAuth permissions, Kiweely Bridge (coming next) executes live WQL with zero stored worker data.

Frequently asked questions

Which WQL worker data source performs fastest for live directory lookups?

indexedAllWorkers provides the fastest response times for active and future-hired worker directory searches because it runs against Workday's indexed data store rather than scanning unindexed terminated worker history.

How do I bypass WQL's 30-minute query result cache when testing org changes?

Workday caches identical GET /data WQL query results for 30 minutes. Pass offset=0 explicitly in the query string (for example, /data?offset=0&query=...) to force a fresh read.

When should I switch from GET /data to POST /data in the WQL REST API?

Use GET /data for queries shorter than 2,048 characters, and switch to POST /data with a JSON body containing the query property for queries between 2,048 and 16,000 characters.

Why does a WQL query return empty costCenter or manager fields for an authenticated caller?

WQL enforces field-level domain security on every selected alias. If the caller has Public Worker Reports access for names and business titles but lacks view permission on organization or staffing domains for that worker population, restricted fields return blank or fail validation.

Sources checked

Related guides

All guides

Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.

We’ll email you once to confirm. Unsubscribe in one click from any issue.