# Fetching a list of Stories This endpoint returns structured Story objects. As with all Kantata OX API endpoints, the returned data will be referenced in sorted order in the `results` array and will be indexed by ID in the `stories` top-level JSON key. Please see our [Response Format](#section/Response-Format) section for more information. Endpoint: GET /stories Version: 1.0.0 ## Query parameters: - `active_between` (string) Filter for tasks that have a start or due date that is within a specified date range. Specify the date range with a pair of colon-separated dates, in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. For example, `2013-06-01:2013-08-01`. - `all_on_account` (boolean) If you are a reports viewer or administrator, you can retrieve all stories on an account. - `archived` (string) Include, filter for, _or_ exclude archived tasks (e.g. `GET https://api.mavenlink.com/api/v1/stories?archived=exclude`). Valid values: `include`, `only`, `exclude`. - `assigned_to_current_user` (boolean) If set to `true`, includes tasks that are assigned to the user making the request. - `by_any_tag` (string) Include tasks with at least 1 of the specified [tags](https://mavenlink.zendesk.com/hc/en-us/articles/360052128794-New-Task-Tracker#Task-Rows). Give multiple tags in a comma-separated list (e.g. `GET /api/v1/stories.json?by_tag_name=design,product management,writing`). Tags (and therefore valid values for tags) are defined by users. - `by_custom_choice_value` (string) Filter by a custom field choice value, represented as a string with the custom field ID, followed by a colon, and then comma-separated custom field choice value IDs. The custom field choice value can also be the word `blank`. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - `custom_field_ID:choice_value_ID` - `custom_field_ID:choice_value_1_ID,choice_value_2_ID` - `custom_field_ID:blank` - `(custom_field_1_ID:choice_value_1_ID,choice_value_2_ID):(custom_field_2_ID:choice_value_3_ID)`. - `by_custom_currency_value` (string) Filter by a custom field currency value, represented as a string with the custom field ID, followed by a colon, and then the currency value. Optionally, the currency [ISO code](https://mavenlink.zendesk.com/hc/en-us/articles/360041576473) can be supplied as well, separated from the currency value by another colon. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - `(1:200.2:USD):(2:100)`. - `by_custom_date_field` (string) Filter for tasks with custom fields that have a date value within a specified range. Specify the custom field ID and date range in a colon-separated string, with dates in a YYYY-MM-DD format. For example, `GET /api/v1/stories.json?by_custom_date_field=18290:2018-05-02:2018-06-01`. Give multiple custom fields with date values in a semicolon-separated list (e.g. `GET /api/v1/stories.json?by_custom_date_field=18290:2018-05-02:2018-06-01;18291:2018-06-15:2018-08-15`). - `by_custom_date_value` (string) Filter by a custom field date value, represented as a string with the custom field ID, followed by a colon, the starting date, another colon, and then the ending date. You can provide both a starting date and ending date, or provide just one. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - `(1:2014-12-05:2014-12-25):(2:2014-12-05)`. - `by_custom_number_value` (string) Filter by a custom field number value, represented as a string with the custom field ID, followed by a colon, and then the number value. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - `(1:200):(2:101)`. - `by_custom_text_value` (string) Filter by a custom field text value, represented as a string with the custom field ID, followed by a colon, and then the text value. Multiple custom fields can be delimited by semicolons or by parentheses and colons. The following formats are supported: - `(1:something):(2:else)` - `(1:something):(1:else)` (multiple values for the same field, returns objects matching any value) - `1` (bare field ID with no value, returns all objects that have any value for that field). - `by_status` (string) Filter by task status. Provide a comma-separated list of task status names. - `by_subtask_count` (integer) Filters for parent tasks with the specified number of subtasks. - `by_tag_name` (string) Include tasks with the exact [tags](https://mavenlink.zendesk.com/hc/en-us/articles/360052128794-New-Task-Tracker#Task-Rows) specified. Give multiple tags in a comma-separated list (e.g. `GET /api/v1/stories.json?by_tag_name=development,data analysis`). Tags (and therefore valid values for tags) are defined by users. - `by_workspace_group` (string) Filter for tasks in projects that belong to a [Project Group](/tag/Workspace-Groups) (ID). Give multiple project group IDs in a comma-separated list. - `completed` (boolean) Filter for only completed tasks. If `false`, no filtering is applied. - `completed_between` (string) Filter for tasks that were completed within the specified date range. Specify the date range with a pair of colon-separated dates, in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. For example, `2013-06-01:2013-08-01`. - `created_after` (string) Filter for records created after a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. - `created_before` (string) Filter for records created before a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. - `creators` (string) Filter for tasks created by the specified user (ID). Give multiple user IDs in a comma-separated list (e.g. `GET https://api.mavenlink.com/api/v1/stories?creators=1,2,3`). - `due_after` (string) Filter for tasks that are due after the specified date. The date must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. - `due_before` (string) Filter for tasks that are due before the specified date. The date must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. - `due_between` (string) Filter for tasks with a due date that is within a specified date range. Specify the date range with a pair of colon-separated dates, in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. For example, `2013-06-01:2013-08-01`. - `due_on` (string) Filter for tasks that are due on the specified date. The date must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. - `exclude_workspace_title_from_search` (boolean) If set to `true`, excludes tasks in projects with a title that matches searched text. - `external_reference_external_message` (string) Filter the objects based on the external message of their associated external references. This is an exact match. - `external_reference_external_status` (string) Filter by the status of the external object in the external system. - `external_reference_service_model` (string) Filter by the type of the external object this external reference belongs to. - `external_reference_service_model_ref` (integer) Filter by the id of the external object this external reference belongs to. - `external_reference_service_model_refs` (string) Filter for objects that correlate to the specified external object IDs. Provide a comma-separated list of up to 200 external IDs. - `external_reference_service_name` (string) Filter by the name of the provider for integration. - `external_reference_status` (string) Filter by the status of the integration, this can be successful or fail. - `has_external_references` (boolean) Filter by whether or not the object has external references. - `has_value_for_custom_field_ids` (string) Filter by the presence of a custom field value for the specified comma-separated custom field ID(s). - `include` (string) Any of the below associations can be included in your request by providing the `include` param, e.g. `include=association1,association2`. - `ancestors` (Story) - Retrieves all of the tasks that the task is nested under (parents and top-level tasks). The response will include `ancestor_ids`, which references the data in the `stories` top-level key. - `assigned_role` (Role) - Retrieves the authenticated user’s assigned role for the task. The response will include `assigned_role_id`, which references the data in the `roles` top-level key. - `assignees` (User) - Retrieves all users assigned to the task, excluding unnamed resources. The response will include `assignee_ids`, which references the data in the `users` top-level key. - `attachments` (Attachments::PostAttachment) - Retrieves all attachments in the task's posts. The response will include `attachment_ids`, which references the data in the `attachments` top-level key. Must be used with the `only` parameter. - `creator` (User) - Retrieves the user who created the task. The response will include `creator_id`, which references the data in the `users` top-level key. - `current_assignments` (Assignment) - Retrieves all assignments for the task. The response will include `current_assignment_ids`, which references the data in the `assignments` top-level key. - `custom_field_values` (CustomFieldValue) - Retrieves the task’s custom field values. The response will include `custom_field_value_ids`, which references the data in the `custom_field_values` top-level key. - `descendants` (Story) - Retrieves all of the subtasks nested under this top-level task. The response will include `descendant_ids`, which references the data in the `stories` top-level key. - `external_references` (ExternalReference) - Includes references to external integrations for this object. - `followers` (User) - Retrieves all users following the task. The response will include `follower_ids`, which references the data in the `users` top-level key. - `google_documents` (GoogleDocument) - Retrieves all Google documents for the task. The response will include `google_document_ids`, which references the data in the `google_documents` top-level key. Must be used with the `only` parameter. - `parent` (Story) - Retrieves the parent task that this subtask is nested directly under. The response will include `parent_id`, which references the data in the `stories` top-level key. - `potential_workspace_resources` (WorkspaceResource) - Retrieves the project's named resources who are not assigned to the task. The response will include `potential_workspace_resource_ids`, which references the data in the `workspace_resources` top-level key. Must be used with the `only` parameter. - `potential_workspace_resources_with_unnamed` (WorkspaceResource) - Retrieves all of the project's resources (named and unnamed) who are not assigned to the task. The response will include `potential_workspace_resources_with_unnamed_ids`, which references the data in the `workspace_resources` top-level key. Must be used with the `only` parameter. - `replies` (Post) - Retrieves all task posts, except for the first one. The response will include `reply_ids`, which references the data in the `posts` top-level key. Must be used with the `only` parameter. - `root` (Story) - Retrieves the top-level task that this subtask is nested under. The response will include `root_id`, which references the data in the `stories` top-level key. - `source_dependencies` (StoryDependency) - Retrieves all tasks that this task is dependent on. The response will include `source_dependency_ids`, which references the data in the `story_dependencies` top-level key. - `story_state_changes` (StoryStateChange) - Retrieves all status changes the task has gone through. The response will include `story_state_change_ids`, which references the data in the `story_state_changes` top-level key. Must be used with the `only` parameter. - `story_tasks` (StoryTask) - Retrieves all checklist items for the task. The response will include `story_task_ids`, which references the data in the `story_tasks` top-level key. - `sub_stories` (Story) - Retrieves all direct subtasks of the task. This does not include the subtasks of its direct subtasks. The response will include `sub_story_ids`, which references the data in the `stories` top-level key. - `tags` (ActsAsTaggableOn::Tag) - Retrieves all tags for the task. The response will include `tag_ids`, which references the data in the `tags` top-level key. - `target_dependencies` (StoryDependency) - Retrieves all tasks that are dependent on this task. The response will include `target_dependency_ids`, which references the data in the `story_dependencies` top-level key. - `workspace` (Workspace) - Retrieves the project the task is in. The response will include `workspace_id`, which references the data in the `workspaces` top-level key. - `workspace_resources` (WorkspaceResource) - Retrieves the named resources who are assigned to the task. The response will include `workspace_resource_ids`, which references the data in the `workspace_resources` top-level key. - `workspace_resources_with_unnamed` (WorkspaceResource) - Retrieves all of the resources (named and unnamed) assigned to the task. The response will include `workspace_resources_with_unnamed_ids`, which references the data in the `workspace_resources` top-level key. - `not_assigned_to_resource` (integer) Filter for tasks not assigned to the specified resource (ID). - `not_assigned_to_user` (integer) Filter for tasks not assigned to the specified user (ID). - `only` (string) Allows you to request one or more resources directly by ID. Multiple IDs can be supplied in a comma separated list, like `GET /api/v1/workspaces.json?only=5,6,7`. - `only_archived` (boolean) If set to `true`, filters for archived tasks. - `only_deleted` (boolean) If set to `true`, filters for deleted tasks. - `only_todos` (boolean) If set to `true`, filters for only To Dos. - `optional_fields` (array) Allows you to request one or more optional fields as an array. - `order` (string) Supply `order` with the name of a valid sort field for the endpoint and a direction. Valid values: `created_at:asc`, `created_at:desc`, `due_date:asc`, `due_date:desc`, `importance`, `parent_and_position`, `position`, `priority_level:asc`, `priority_level:desc`, `start_date:asc`, `start_date:desc`, `updated_at:asc`, and `updated_at:desc`. - `page` (integer) - `parents_only` (boolean) Filter for top-level tasks. This does not include subtasks that have other subtasks nested under them. - `per_page` (integer) - `priority` (string) Filter for tasks with the specified priorities. Give multiple priorities in a comma-separated list (`GET https://api.mavenlink.com/api/v1/stories?priority=critical,high`). Valid values: `critical`, `high`, `normal`, `low`. - `search` (string) - `show_archived` (boolean) If set to `true`, includes archived tasks in the response. - `show_deleted` (boolean) If set to `true`, includes deleted tasks. - `show_from_archived_workspaces` (boolean) If set to `true`, filters for tasks in archived projects. - `show_todos` (boolean) If set to `true`, includes To Dos in the response. - `starting_between` (string) Filter for tasks with a start date that is within a specified date range. Specify the date range with a pair of colon-separated dates, in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. For example, `2013-06-01:2013-08-01`. - `story_type` (string) Include tasks of the specified type. Valid values: `task`, `milestone`, `deliverable`, `issue`. - `story_types` (string) Filter for tasks of the specified type(s). Give multiple task types in a comma-separated list. - `time_trackable_on_workspace_id` (integer) Filter for tasks that [time can be tracked against](https://mavenlink.zendesk.com/hc/en-us/articles/360008143214) in the specified project (ID). - `uncompleted` (boolean) Filter for only incomplete tasks. If `false`, no filtering is applied. - `updated_after` (string) Filter for records updated after a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. - `updated_before` (string) Filter for records updated before a specified datetime. The datetime must be in [ISO 8601](https://www.w3.org/TR/NOTE-datetime) format. - `with_ancestry_depth` (integer) Include [subtasks](https://mavenlink.zendesk.com/hc/en-us/articles/205221350) that are nested at the specified level from the top-level task (e.g. `GET /api/v1/stories.json?with_ancestry_depth=3`). The top-level task is considered to be at the 0 level. Subtasks can be nested up to 4 levels from the top-level task. - `with_assignees` (string) Filter for tasks assigned to the specified users. Give multiple user IDs in a comma-separated list (e.g. `GET https://api.mavenlink.com/api/v1/stories?with_assignees=1,2,3`). In addition to user IDs, you can also pass `unassigned` and `unnamed`. These can be included in a comma-separated list (e.g. `GET https://api.mavenlink.com/api/v1/stories?with_assignees=1,2,3,unassigned,unnamed`). `unassigned` returns tasks that are not assigned to any users. `unnamed` returns tasks assigned to unnamed resources. - `with_followers` (string) Filter for tasks with the specified followers. Give multiple user IDs in a comma-separated list. - `with_parent_id` (integer) Filter for [subtasks](https://mavenlink.zendesk.com/hc/en-us/articles/205221350) that are directly nested under the specified task (ID). - `with_projects` (string) Include tasks in the specified projects. Give multiple project IDs in a comma-separated list. - `with_root_id` (integer) Filter for [subtasks](https://mavenlink.zendesk.com/hc/en-us/articles/205221350) that are nested at any level under the specified task (ID). - `with_start_or_due_date` (string) Filter for tasks with start or due dates. - `without_external_reference_service_name` (string) Exclude by the existence of an external reference with the specified service name. - `without_past_completed` (boolean) If set to `true`, filters for tasks that haven't previously been marked as completed. - `workspace_id` (integer) Filter for tasks from the specified project (ID). ## Response 200 fields (application/json): - `count` (integer) - `meta` (object) - `meta.count` (integer) - `meta.page_count` (integer) - `meta.page_number` (integer) - `meta.page_size` (integer) - `results` (array) - `results.key` (string) - `results.id` (string) ## Response 400 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 401 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 403 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 404 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 422 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string) ## Response 503 fields (application/json): - `errors` (array) - `errors.type` (string) - `errors.message` (string)