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 levelsmanager_Level01(CEO / top level) throughmanager_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:
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 0Cache Tip: Workday caches
GET /dataWQL results for 30 minutes. Includingoffset=0as a URL query parameter (/data?offset=0&query=...) forces Workday to bypass the 30-minute cache and return live post-transaction state.
2. Traversing Related Business Objects ({} Notation)
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:
SELECT worker,
businessTitle,
workersManager{businessTitle, email_PrimaryWorkOrPrimaryHome} AS managerDetails,
supervisoryOrganization,
supervisoryOrganization_Superior,
costCenters
FROM indexedAllWorkers
WHERE workerActive = trueKeep two strict WQL RBO rules in mind:
- 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.
- No
{}InsideGROUP BY: You cannot select{}RBO sub-fields in a query that contains aGROUP BYclause, and third-party HTTP clients must URL-encode{(%7B) and}(%7D) when callingGET /data. For queries between 2,048 and 16,000 characters—or to avoid URL-encoding curly braces—sendPOST /data:
{
"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:
SELECT supervisoryOrganization,
costCenter_Name,
count(worker) AS workerCount
FROM workersForHCMReporting
WHERE workerActive = true
GROUP BY supervisoryOrganization, costCenter_NameSecurity 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:
- WQL Execution Access: The caller’s security group must hold
Get/Viewpermission on the Workday Query Language (System/Core Reporting) domain and the API client must include the corresponding Functional Area scopes. - Public Directory vs. Restricted Worker Fields:
- Standard directory fields (
worker,businessTitle,supervisoryOrganization,workersManager,location, public workemail_PrimaryWorkOrPrimaryHome) are typically governed byPerson Data: Public Worker ReportsandWorker Data: Public Worker Reports(similar to theSearch: Find Workerdomain backing theFind Workersreport). - Organization Visibility overrides (
VisibilityonCreate Supervisory Organization) hide restricted supervisory organizations even from callers with broad role-based security. - Multiple-job nuance: just as Workday’s
Find Workersfacets suppress primary-only facets on multi-job workers unless scoped tojobProfilePrimaryorposition, always verify whether your workforce holds multiple concurrent positions (indexedPositionsAndJobs_AllStaffingModels) before assuming a 1:1 worker-to-cost-center mapping.
- Standard directory fields (
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 SelforManagerOAuth grant to verify no field throws a permission error. - Paginate Explicitly: Always pass
limitandoffsetwhen a supervisory subtree can exceed default page sizes. - Filter
workerActive = true: BothallWorkersandworkersForHCMReportinginclude terminated workers by default; omittingworkerActive = truepollutes 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.