---
id: scope-projects
title: 'Scopes and Projects'
description: 'Understanding Scope - the asset behind Projects - its hierarchy, lifecycle and role in queries and permissions'
sidebar_label: 'Scopes & Projects'
sidebar_position: 5
tags: ['concepts', 'scope', 'projects']
---

`Scope` is the asset type behind what the UI calls a **Project**. Scopes form
a tree, every work item belongs to exactly one, and they are the boundary for
permissions and the primary dimension for reporting.

## Key Attributes

| Attribute                            | Type              | Notes                                                       |
| ------------------------------------ | ----------------- | ------------------------------------------------------------ |
| `Name`                               | Text              | **Required**                                                  |
| `Parent`                             | Relation          | **Required** — the containing scope                           |
| `BeginDate`                          | Date              | **Required**                                                  |
| `Scheme`                             | Relation          | **Required** — controls available list values and roles; shown in the UI as **Project Workspace** |
| `EndDate`                            | Date              | Optional — and [exclusive](/apis/conventions/dates): the stored date is the day *after* the last day |
| `Description`                        | LongText          |                                                               |
| `Status`                             | Relation          | Descriptive list value — not the lifecycle (see below)        |
| `Owner`                              | Relation          | A Member                                                      |
| `Members`                            | Relation (multi)  | Members with access — see [roles and permissions](/reference/roles-and-permissions) |
| `Schedule`                           | Relation          | Where the scope's Timeboxes come from                         |
| `Children`, `Workitems`              | Relation (multi, read-only) | System-maintained rollups                           |
| `ParentMeAndUp`, `ChildrenMeAndDown` | Relation (multi, read-only) | Self-plus-ancestors / self-plus-descendants — the subtree workhorses |

## The Tree and Its Root

Every instance has a single root scope — **`Scope:0`, "System (All
Projects)"**, whose `Parent` is null. Everything else hangs beneath it:

```text
Scope:0  System (All Projects)
 └─ Scope:1308  Release 1.0
     └─ …
```

### Walk the Tree Without Recursion

The rollup relations answer ancestry questions in one query — never write a
recursive loop over `Parent`:

```json
{
  "from": "Scope",
  "where": { "ID": "Scope:1308" },
  "select": ["Name", "Parent.Name", "ParentMeAndUp.Name", "ChildrenMeAndDown.Name"]
}
```

And the single most useful filter in Agility — *work in this project or any
project beneath it*:

```json
{
  "from": "Story",
  "filter": ["Scope.ParentMeAndUp='Scope:1308'"],
  "select": ["Number", "Name", "Scope.Name"],
  "page": { "size": 50, "start": 0 }
}
```

See [Relations](/concepts/relations#derived-and-rollup-relations) for why
that filter reads backwards and still means "subtree".

## Creating a Scope

Four attributes are required: `Name`, `Parent`, `BeginDate` and `Scheme`.
The simplest correct pattern copies the parent's scheme:

```json
[
  {
    "AssetType": "Scope",
    "Name": "API Gateway Project",
    "Parent": "Scope:1308",
    "BeginDate": "2026-09-01",
    "Scheme": "Scheme:1001"
  }
]
```

(Read the parent's `Scheme` first:
`{"from": "Scope", "where": {"ID": "Scope:1308"}, "select": ["Scheme"]}`.)

## Lifecycle

- **Closing a project is an operation, not a status change**:
  `?op=Inactivate` sets `AssetState` to Closed (the UI calls closed scopes
  *Inactive*). `Reactivate` reopens. The `Status` attribute is a descriptive
  list value and does not drive the lifecycle.
- **`EndDate` is exclusive** — a project that ends December 31 stores
  January 1. See [date conventions](/apis/conventions/dates) before doing
  arithmetic.
- `Delete` / `Undelete` behave as everywhere:
  [soft delete, recoverable](/concepts/operations#the-lifecycle-quartet).
- Two scope-specific operations worth knowing exist:
  `AssignMemberWithRole` (grant a member a role on the scope — the
  API-friendly way to provision access; see
  [roles and permissions](/reference/roles-and-permissions)) and
  `ConvertToTeam`.

## Scope Vs Timebox

Both group work, on different axes:

- **Scope answers "where does this work live?"** — organizational,
  hierarchical, permission-bearing, long-lived.
- **Timebox answers "when is it planned?"** — sequential sprints/iterations
  that work moves through.

They meet through `Schedule`: a scope points at a Schedule, and the
Timeboxes on that schedule are the sprints available to work in that scope.
Scopes sharing a Schedule share sprint cadence.

## Querying by Scope

```json
// exactly this project
{ "from": "Story", "where": { "Scope": "Scope:1308" },
  "select": ["Number", "Name"], "page": { "size": 50, "start": 0 } }
```

```json
// this project and everything beneath it
{ "from": "Story", "filter": ["Scope.ParentMeAndUp='Scope:1308'"],
  "select": ["Number", "Name"], "page": { "size": 50, "start": 0 } }
```

```json
// across all projects, in one paged sweep — filter later, not never
{ "from": "PrimaryWorkitem", "filter": ["AssetState!='Dead'"],
  "select": ["Number", "Name", "Scope.Name"], "page": { "size": 200, "start": 0 } }
```

## Moving Work Between Scopes

Set the work item's `Scope`; its Tasks and Tests follow automatically —
`Task.Scope` is read-only and derives from the parent:

```json
{ "from": "Story:1207", "update": { "Scope": "Scope:1400" } }
```

## Permissions

A member's access is granted **per scope**, through roles — the scope tree
is the permission tree. The details (Rights vs Privileges, the thirteen
roles, why display names lie) live in
[Roles and permissions](/reference/roles-and-permissions); the read-only
view of assignments is [api/ProjectRoles](/apis/project-roles).

## Related Topics

- [Relations](/concepts/relations) — rollup relations and the subtree idiom
- [Date conventions](/apis/conventions/dates) — exclusive EndDate
- [Roles and permissions](/reference/roles-and-permissions)
- [Query size and performance](/guides/query-size-and-performance)