Retrieve feeds — list, count, or list-latest (unified endpoint)
GET /task/v1/feeds/{retrieve-type}
Operation id: retrieveFeedsByType
Description
Unified endpoint for three feed retrieval modes controlled by retrieve-type path variable.
Misrouted sub-resource URLs: When feed_key is omitted, paths such as /task/v1/feeds/notes, /task/v1/feeds/history, or /task/v1/feeds//attachments are routed here instead of the intended /{feed_key}/… handler. Returns 400 E105 (not E205). Detected segments: notes, history, details, content, attachments, survey, feed-msg-info, pre-requisites, key-attributes.
Session-derived values (domain_id, user_id, unit_id, dept_id, profile_id, time_zone_long, lang_code) are resolved from the auth token and cannot be overridden by query parameters — except in requested-unit / requested-user (RU) mode (v_request_type=ru), which overwrites unit_id, user_id, profile_id, and dept_id in-memory before feed processing (see Requested unit / user identity below). Query params are auto-converted from snake_case to camelCase. All response keys are returned in snake_case.
Retrieve Types
| Value | Description |
|---|---|
list | Paginated feed list with cursor-based pagination. Supports projections, sorting, all filters. |
count | Aggregated priority/total counts for a date range. Requires start_date + end_date. |
list-latest | Incremental delta since a given timestamp for polling. Supports projections but NOT pagination. |
Looking for dashboard counts (status / priority / due tiles)? Those moved to a dedicated endpoint at
GET /task/v1/dashboard/{retrieve-type}withretrieve-type=feed-entity-count. See that operation below.
Parameter Applicability Matrix
Legend: ✅ = accepted/used | REQ = required | — = not applicable (silently ignored)
| Parameter | list | count | list-latest | Default |
|---|---|---|---|---|
projections | ✅ | — | ✅ | all default feed fields |
limit | ✅ | — | — | 20 |
starting_after | ✅ | — | — | null |
ending_before | ✅ | — | — | null |
start_date | — | REQ | — | — |
end_date | — | REQ | — | — |
today_from | — | — | ✅ | 0 |
from_time | — | — | ✅ | 0 |
feed_keys | — | — | ✅ | null |
selected_dates | ✅ | — | ✅ | null |
cut_off_time | ✅ | ✅ | — | 0 |
pin | ✅ | ✅ | ✅ | -1 |
favorite | ✅ | ✅ | ✅ | -1 |
follow | ✅ | ✅ | ✅ | -1 |
message_type | ✅ | ✅ | ✅ | null |
status | ✅ | ✅ | ✅ | null |
priority | ✅ | ✅ | ✅ | null |
feed_title | ✅ | ✅ | ✅ | null |
acknowledge_flag | ✅ | ✅ | ✅ | -1 |
promote_to_note_flag | ✅ | ✅ | ✅ | -1 |
com_attr_val | ✅ | ✅ | ✅ | null |
msg_attr_val | ✅ | ✅ | ✅ | null |
view_type | ✅ | ✅ | ✅ | MV |
dept_id | ✅ (DV only) | ✅ (DV only) | ✅ (DV only) | session |
task_view | ✅ | ✅ | ✅ | P |
return_type | ✅ | ✅ | — | null |
feed_type_id | ✅ | ✅ | ✅ | null |
tags | ✅ | ✅ | ✅ | null |
sort_by | ✅ | — | — | null |
sort_order | ✅ | — | — | null |
return_format | ✅ | — | — | J |
filter_id | ✅ | — | ✅ | null |
week_dates | ✅ | — | ✅ | null |
v_request_type | ✅ | — | ✅ | (absent) |
v_requested_unit_id | ✅ (RU) | — | ✅ (RU) | — |
v_requested_user_id | ✅ (RU) | — | ✅ (RU) | — |
v_requested_profile_id | ✅ (RU) | — | ✅ (RU) | kernel backfill |
v_requested_dept_id | ✅ (RU) | — | ✅ (RU) | kernel backfill |
RU identity params apply to
listandlist-latestonly — notcount.
Requested unit / user (RU) identity
Corporate users pass v_request_type=ru with a corp auth token to view a requested store unit's feeds. RequestedViewIdentityResolver mutates four session fields in-memory before the feed query: unitId, userId, profileId, deptId. When the effective requested user id (omitted, blank, or -1 → -1) does not equal the token userId, alternateUsers is cleared (null).
view_type vs task_view: view_type (MV/SV/DV) controls line-of-sight and RU validation rules. task_view (P/TV) controls row granularity (project cards vs task rows). They are independent.
RU resolution branches
| Condition | Session update | Result |
|---|---|---|
v_request_type absent or not ru | unchanged | Token session |
RU + view_type=SV + no v_requested_user_id | unitId←payload; userId/profileId/deptId←-1 | Store-wide at unit; confidential feeds excluded |
RU + view_type=SV + user | all four from payload/kernel | User-scoped SV |
| RU + MV/DV + user | all four from payload/kernel | User-scoped MV/DV |
| RU + MV/DV + no user | — | E113 |
RU + missing v_requested_unit_id | — | E107 |
| RU + user not in unit | — | E178 |
| RU + invalid profile subset | — | E179 |
| RU + invalid dept subset | — | E180 |
| RU + user not found (kernel) | — | E404 |
Confidential feeds: RU + view_type=SV without v_requested_user_id (omitted / -1) does not return confidential feeds. Pass v_requested_user_id to include confidential items visible to that user.
Cursor-Based Pagination (list only)
- Initial request: No cursor params —
GET /task/v1/feeds/list?status=N&limit=20 - Response includes:
has_more,next_cursor(base64 opaque),previous_cursor,last_fetch_time - Next page (forward):
?...&starting_after=<next_cursor value> - Previous page (backward):
?...&ending_before=<previous_cursor value>
Rules:
- Use only one of
starting_afterorending_beforeper request — providing both → E206 - Cursors are opaque strings — do not parse or construct them manually
limitis clamped to 1–100: values below 1 default to 20, values above 100 cap at 100has_more: falsemeans no further pages in the requested direction
Projections — Default Fields
When projections is omitted, the following default fields are returned for each feed object. feed_key is always included regardless of what is requested.
feed_key, feed_title, message_type, status, priority, feed_type, feed_type_id, cluster_id, cluster_child_id, start_date_time, end_date_time, display_launch_date, create_dtm, last_updated_time, task_count, overdue_task_count, pin, pinned, favorite_flag, acknowledged_flag, is_confidential, has_survey, title_css, panel_config, assign_to_desc, has_comments, enable_comment, future_feed, show_why_url, has_action, enable_action, show_how_url, has_history, has_user_notes, has_actions, has_contents, has_key_attributes, project_title, parent_feed_key, last_action_time, last_action_time_in_millis
Note:
project_titleandparent_feed_keyare only present on Task records (cluster_child_id != -1). Forlist, they appear only whentask_view=TV. Forlist-latest, they are always present on Task records sincelist-latestalways operates in Task View internally. Project-without-task records (cluster_child_id = -1) do not carry these fields.
Note (TM-74802): boolean
pinnedis stamped when domainTASK_PIN_COUNT > 0(home-unitTASK_PINSmembership). Legacy integerpinremains. Pin CRUD lives undermywork/v1/user-preferences; pin-open UX usesGET /task/v1/feeds/{feed_key}/visibility.
Projections — Additional Available Fields
These fields are not in the default set but can be explicitly requested:
transaction_key, feed_owner, feed_type_id_desc, ext_link_info, dept_id, end_date_utc, display_start_date, profile_id, display_date, has_predecessor, show_acknowledge, last_updated_time_in_millis, event_date, additional_attributes, show_claim, promote_to_note_flag, update_all_mul_asg_task_attr, flag, is_edited, allow_future_quick_links, thread_flag, acknowledge_flag, txn_dtm, lock_status, start_date_utc, unit_id, action_taken_flag, time_to_act, feed_description, feed_params, event_end_date, watch_flag, follow, user_id, feed_task_count, display_end_date
Note:
filter_idoverrides the standard query path — when provided, the system uses theMwFilterConfigfor data retrieval instead of applying the filter params above.
Error Scenarios
| Scenario | HTTP | Error Code | Message |
|---|---|---|---|
Missing X-reflexis-csrf-token-X header | 400 | E112 | X-reflexis-csrf-token-X header is mandatory |
| Invalid or expired token | 401 | E204 | Invalid or expired token |
Misrouted feed sub-resource URL (missing feed_key), e.g. /feeds/notes, /feeds/history | 400 | E105 | feed_key is mandatory |
Invalid retrieve-type value | 400 | E205 | Invalid retrieve-type. Allowed values: list, count, list-latest |
Both starting_after and ending_before provided | 400 | E206 | Cannot use both starting_after and ending_before simultaneously. |
Missing start_date for count | 400 | E114 | start_date is required for count. |
Missing end_date for count | 400 | E115 | end_date is required for count. |
Refresh interval exceeded (list-latest) | 400 | E116 | Refresh interval exceeded maximum allowed limit. |
RU: missing v_requested_unit_id | 400 | E107 | Unit id is mandatory |
RU: MV/DV without v_requested_user_id | 400 | E113 | v_requested_user_id is mandatory |
RU: user not in v_requested_unit_id | 400 | E178 | Requested user does not belong to the provided unit |
RU: invalid v_requested_profile_id | 400 | E179 | Invalid v_requested_profile_id for the requested user |
RU: invalid v_requested_dept_id | 400 | E180 | Invalid v_requested_dept_id for the requested user |
| RU: requested user not found | 200 | E404 | No data found |
| No data found | 200 | E404 | No data found |
Error Codes Reference
| Code | Description |
|---|---|
E105 | Misrouted feed sub-resource URL — missing or invalid feed_key |
E205 | Invalid retrieve-type path variable |
E206 | Both pagination cursors provided simultaneously |
E114 | Missing start_date for count |
E115 | Missing end_date for count |
E116 | Refresh interval exceeded for list-latest |
E107 | RU: missing or invalid v_requested_unit_id |
E113 | RU: mandatory parameter missing (typically v_requested_user_id for MV/DV) |
E178 | RU: requested user does not belong to the provided unit |
E179 | RU: v_requested_profile_id not in user's kernel profiles |
E180 | RU: v_requested_dept_id not in user's kernel departments |
E204 | Invalid or expired token |
E404 | No data found (includes RU kernel user lookup failure) |
Tags: MyWorkFeeds
Parameters
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
retrieve-type | string | Yes | Retrieve mode for /task/v1/feeds/{retrieve-type}: - list — paginated feed list with cursor-based pagination - count — aggregated count by priority (requires start_date/end_date) - list-latest — incremental delta since last fetch timestamp For dashboard counts, use /task/v1/dashboard/{retrieve-type} with retrieve-type=feed-entity-count instead. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
acknowledge_flag | integer | No | Acknowledge filter: -1=all, 0=not acknowledged, 1=acknowledged |
com_attr_val | string | No | Communication attribute value filter |
cut_off_time | integer (int64) | No | Cut-off time in epoch ms (list, count) |
dept_id | string | No | Optional comma-separated department ids. When present, requires view_type=DV and each id must be in the user's line of sight (E217 / E214 / E216). When omitted, session dept_id is used. |
end_date | string | No | End date in YYYYMMDD format. Required for count retrieve-type. |
ending_before | string | No | Backward pagination cursor — use previous_cursor from previous response (list only) |
favorite | integer | No | Favorite filter: -1=all, 0=not favorite, 1=favorite |
feed_keys | string | No | Comma-separated feed keys to check for updates (list-latest only) |
feed_title | string | No | Text search on feed title (URL-encoded values are auto-decoded) |
feed_type_id | string | No | Feed type ID filter (e.g. CL0) |
filter_id | string | No | System filter ID. When provided, loads MwFilterConfig and uses it for data retrieval (list, list-latest). For list, the client-supplied limit overrides the filter's stored PAGINATION_LIMIT. |
follow | integer | No | Follow filter: -1=all |
from_time | integer (int64) | No | Epoch ms of last fetch — incremental delta anchor. Always > today_from (it is a recent poll time, not start of day). Must be a real timestamp from last_fetch_time in a prior list response. Passing 0 returns HTTP 200 with an empty array (no DB query — signals first call). Timestamps older than MAX_REFRESH_TIME (default 1 hour) → HTTP 400 E116 (list-latest only). |
limit | integer | No | Max records per page (list only; clamped to 1-100) |
message_type | string | No | Feed message type code (e.g. DOWNLOADFILEMSG, PROJECTEXTRACT, RWS41_ADVERTISE_SHIFT_RES_MANAGER_NOTIFICATIONS) |
msg_attr_val | string | No | Message attribute value filter |
pin | integer | No | Pin filter: -1=all, 0=not pinned, 1=pinned |
priority | string | No | Comma-separated priority integers (e.g. 4 or 1,2,3) |
projections | string | No | Comma-separated field names to include in each feed object (list, list-latest). Omit to return the default field set documented above (project_title and parent_feed_key when applicable). feed_key is always included. Additional available fields: transaction_key, feed_owner, ext_link_info, dept_id, end_date_utc, additional_attributes, watch_flag, feed_params, etc. |
promote_to_note_flag | integer | No | Promote-to-note filter: -1=all |
return_format | string | No | Return format (list only): J=JSON |
return_type | string | No | Return type filter (e.g. CALENDAR) |
selected_dates | string | No | Comma-separated dates in YYYYMMDD format (e.g. 20260309,20260324). Applies to list, list-latest. |
sort_by | string | No | Comma-separated sort columns (list only): profileId, endDateTime, priority, startDateTime, feedTitle, feedTypeId |
sort_order | string | No | Comma-separated sort directions matching sort_by (list only): A=ascending, D=descending |
start_date | string | No | Start date in YYYYMMDD format. Required for count retrieve-type. |
starting_after | string | No | Forward pagination cursor — use next_cursor from previous response (list only) |
status | string | No | Comma-separated status codes: N=New, R=Reviewed, P=In Progress, O=Overdue, C=Completed, F=Force-closed, E=Expired |
tags | string | No | Tags filter |
task_view | string | No | Row granularity: P=Project View (project cards), TV=Task View (task rows). Independent of view_type. |
today_from | integer (int64) | No | Epoch ms — start of today (day-scope boundary). Always ≤ from_time. Not the same as from_time: today_from is today's midnight anchor; from_time is the exact last-poll timestamp (list-latest only). |
v_request_type | string | No | Requested-unit / requested-user (corp) identity mode for feed retrieve endpoints. Case-insensitive ru activates in-memory overrides of unitId, userId, profileId, and deptId on the authenticated session before feed processing. Omitted → store-user token session. Any other value is ignored (no error; session unchanged). Applied to list, list-latest, and /list/tasks. Not applied when retrieve-type=count. |
v_requested_dept_id | string | No | Optional comma-separated department subset for the requested user (RU + user path). Each value must belong to the user's kernel departments → E180. When omitted, backfilled from kernel (deptIds / deptId); sentinel -1 if none. |
v_requested_profile_id | string | No | Optional comma-separated profile subset for the requested user (RU + user path). Each value must belong to the user's kernel profiles → E179. When omitted, backfilled from kernel (profileIds / profileId); sentinel -1 if none. |
v_requested_unit_id | string | No | Target store unit ID for RU mode. Required when v_request_type=ru. Missing or -1 → E107. |
v_requested_user_id | string | No | Impersonated store user for RU mode. Required when view_type is MV or DV (including default MV). Optional for SV — omit for store-wide view. Omitted or -1 is treated as absent. MV/DV without user → E113. SV without user: confidential feeds are not returned; supply a user id to evaluate confidential visibility for that user. |
view_type | string | No | Line-of-sight scope: MV=My View, DV=Department View, SV=Store View. Also drives RU validation (v_requested_user_id optional for SV, required for MV/DV). |
week_dates | string | No | Comma-separated week dates in YYYYMMDD format (e.g. 20260322,20260323,...,20260328). For list, this constrains the selected date range (and is used when selected_dates is omitted). For list-latest, it is applied only when filter_id is provided. |
Security
- ApiKeyHeader (apiKey)
- APIGEE API key header validated by VerifyAPIKey policy.
- AuthTokenHeader (apiKey)
- Session authentication token validated server-side against the user session store.
Responses
200 — list → {feed_details[], previous_cursor, next_cursor, has_more, last_fetch_time} — or E404 no data.
count → {count_data: {priorities[], total}}. list-latest → {feed_list_latest[], status}.
Content type: application/json
400 — - E105 — misrouted feed sub-resource URL (missing feed_key)
- E205 — invalid retrieve-type
- E206 — both starting_after and ending_before provided
- E114 — missing start_date for count
- E115 — missing end_date for count
- E116 — refresh interval exceeded for list-latest
- E107 — RU missing v_requested_unit_id
- E113 — RU MV/DV missing v_requested_user_id
- E178 — RU user not in requested unit
- E179 — RU invalid v_requested_profile_id
- E180 — RU invalid v_requested_dept_id
Content type: application/json
401 — Invalid or expired X-reflexis-csrf-token-X token (HTTP 401)
Content type: application/json
500 — Unexpected server-side error
Content type: application/json
Response models
200 — list → {feed_details[], previous_cursor, next_cursor, has_more, last_fetch_time} — or E404 no data.
count → {count_data: {priorities[], total}}. list-latest → {feed_list_latest[], status}.
Content type: application/json
Schema
JSON object (structure varies by endpoint).
{
"type": "object",
"description": "JSON object (structure varies by endpoint)."
}
Example:
{
"status": "OK",
"feed_details": [],
"previous_cursor": null,
"next_cursor": "eyJza2lwIjoyMH0=",
"has_more": true,
"last_fetch_time": 1774373200310
}
400 — - E105 — misrouted feed sub-resource URL (missing feed_key)
- E205 — invalid retrieve-type
- E206 — both starting_after and ending_before provided
- E114 — missing start_date for count
- E115 — missing end_date for count
- E116 — refresh interval exceeded for list-latest
- E107 — RU missing v_requested_unit_id
- E113 — RU MV/DV missing v_requested_user_id
- E178 — RU user not in requested unit
- E179 — RU invalid v_requested_profile_id
- E180 — RU invalid v_requested_dept_id
Content type: application/json
Schema
| Property | Type | Required | Description |
|---|---|---|---|
status | string | Yes | Always "ER" for error responses |
errorCode | string | Yes | Application-level error code (e.g. E204, E112, E302) |
response | string | Yes | Human-readable error message |
{
"type": "object",
"example": {
"status": "ER",
"errorCode": "E204",
"response": "Invalid or expired token"
},
"required": [
"status",
"errorCode",
"response"
],
"properties": {
"status": {
"type": "string",
"description": "Always \"ER\" for error responses",
"enum": [
"ER"
]
},
"errorCode": {
"type": "string",
"description": "Application-level error code (e.g. E204, E112, E302)"
},
"response": {
"type": "string",
"description": "Human-readable error message"
}
}
}
401 — Invalid or expired X-reflexis-csrf-token-X token (HTTP 401)
Content type: application/json
Schema
| Property | Type | Required | Description |
|---|---|---|---|
status | string | Yes | Always "ER" for error responses |
errorCode | string | Yes | Application-level error code (e.g. E204, E112, E302) |
response | string | Yes | Human-readable error message |
{
"type": "object",
"example": {
"status": "ER",
"errorCode": "E204",
"response": "Invalid or expired token"
},
"required": [
"status",
"errorCode",
"response"
],
"properties": {
"status": {
"type": "string",
"description": "Always \"ER\" for error responses",
"enum": [
"ER"
]
},
"errorCode": {
"type": "string",
"description": "Application-level error code (e.g. E204, E112, E302)"
},
"response": {
"type": "string",
"description": "Human-readable error message"
}
}
}
Example:
{
"status": "ER",
"errorCode": "E204",
"response": "Invalid or expired token"
}
500 — Unexpected server-side error
Content type: application/json
Schema
| Property | Type | Required | Description |
|---|---|---|---|
status | string | Yes | Always "ER" for error responses |
errorCode | string | Yes | Application-level error code (e.g. E204, E112, E302) |
response | string | Yes | Human-readable error message |
{
"type": "object",
"example": {
"status": "ER",
"errorCode": "E204",
"response": "Invalid or expired token"
},
"required": [
"status",
"errorCode",
"response"
],
"properties": {
"status": {
"type": "string",
"description": "Always \"ER\" for error responses",
"enum": [
"ER"
]
},
"errorCode": {
"type": "string",
"description": "Application-level error code (e.g. E204, E112, E302)"
},
"response": {
"type": "string",
"description": "Human-readable error message"
}
}
}
Example:
{
"status": "ER",
"errorCode": "E302",
"response": "Internal server error"
}