---
id: faq
slug: /faq
title: 'FAQ - Frequently Asked Questions'
description: 'Short answers to the questions Agility API integrators actually ask'
sidebar_label: 'FAQ'
sidebar_position: 9
tags: ['faq']
---

## Authentication

**How do I get an API token?** Member menu (your avatar) → **Applications**
→ add a personal application. The token shows **once**. Admins can disable
tokens instance-wide. [Authentication](/getting-started/authentication).

**What headers do I need?** `Authorization: Bearer <token>`,
`Content-Type: application/json`, `Accept: application/json`. `meta.v1`
needs no auth at all. (Basic authentication exists but is effectively a
dev/demo setting — production instances use SSO, where tokens are the
path.)

**How long do access tokens last?** They don't expire. A token is valid
until revoked (Applications page) or until tokens are disabled
instance-wide — so rotate deliberately;
[nothing rotates for you](/getting-started/authentication#token-lifecycle).

**Can I limit what a token can do?** No — a token always acts with the
full rights and privileges of its member. Run integrations as a dedicated
member with a minimal role.

## Querying

**Why is my query returning empty results?** Usually not an error: check
the filter (values quoted? OIDs not names?), whether the asset is closed or
deleted, and whether you hit a
[silent trap](/troubleshooting) — most Agility traps return `200` with
wrong data rather than failing.

**What shape is the response?** `query.v1` returns an **array of result
arrays** — no `results` or `query` wrapper. Dotted selections arrive as
flattened keys (`"Scope.Name"`), bare relations as `{"_oid": …}` objects.
[Examples](/examples/curl) show real responses.

**How do I query custom fields?** Exactly like any attribute, using the
full token from `meta.v1` (usually `Custom_…`). Discover them there —
[not by sampling data](/concepts/assets#the-asset-type-hierarchy).

**What's the maximum page size?** None is documented — which is not an
invitation. Very large pages combined with wide projections can hang;
hundreds to low thousands per page works well.
[Query size and performance](/guides/query-size-and-performance).

## Writing

**Why did my create/update "fail silently"?** It didn't — the Bulk API
answers `200` with failures itemised in `commandFailures`. Check
`commandFailures.count` on every response.
[Errors and partial failures](/apis/asset-bulk/errors).

**How do I find valid status OIDs?** Query the list type
(`StoryStatus`, sorted by `Order`) — and note a team using a Team Process
restricts which values its items may enter.
[Workflows](/concepts/workflows).

**Can I update multiple assets at once?** Yes — one `api/asset` request
carries many commands, and later commands can
[reference earlier ones by alias](/apis/asset-bulk/aliases-and-projection).

**What's the difference between `set`, `add` and `remove`?** `set`
replaces a value (or a whole multi-relation); `add`/`remove` adjust a
multi-relation's membership.
[Relation updates](/apis/asset-bulk/relation-updates).

**Why can't I delete an asset?** If it's closed:
`Violation'AssetCannotDeleteClosed` — reactivate first, then delete. And
remember [Inactivate is not Delete](/concepts/operations#the-lifecycle-quartet).

**Why can't I edit a closed asset?** Closed assets accept **backfill
only** — attributes that had no value. Changing an existing value fails
with `Violation'ClosedAssetCannotEditExistingValues`; reactivate to edit.

**Can I change an asset's AssetType?** Not by update — but conversion
operations exist where it makes sense (`ConvertToDefect`,
`ConvertToTeam`). Check the type's operations in `meta.v1`.

## Performance

**Is there a rate limit?** When rate limiting is enabled, your instance uses
[configured quota policies](/guides/rate-limiting), and your queries also
share a database with every interactive user —
[slow queries are everyone's problem](/guides/query-size-and-performance).

**Should I use parallel requests?** Modestly. A handful of concurrent
requests is fine; wide fan-out of heavy queries degrades the instance.
Prefer fewer, larger, well-projected pages.
[Performance](/guides/performance).

**Why are my requests timing out?** The SQL timeout is per query, not per
request — and a near-timeout query is a signal to narrow projection,
filter or page size, not to raise the client timeout.

## Data Model

**What's the difference between Scope and Timebox?** Scope answers *where
does the work live* (organizational, permission-bearing); Timebox answers
*when is it planned* (sprints, via the scope's Schedule).
[Scopes and projects](/concepts/scope-projects).

**What's an OID?** `AssetType:id` — the permanent identifier
(`Story:1207`). A third part names a historical moment.
[Assets](/concepts/assets#object-ids-oids).

**How do parent-child relationships work?** There are several hierarchies:
`Super`/`Subs` for portfolio (Epics), `Parent`/`Children` for
theme-classification *and* task breakdown — `Parent` means different
things by level. [Relations](/concepts/relations#the-hierarchies-at-a-glance).

## Practices

**What's the recommended way to change status?** An ordinary attribute
update, by OID, on either write surface — there is no transition graph to
walk, but Team Process value restrictions are enforced.
[Workflows](/concepts/workflows#changing-status).

**Should I cache API responses?** Cache the stable things — `meta.v1`,
status lists, localization — and invalidate on surprises.
[Performance](/guides/performance#cache-what-is-stable).

**How do I handle large migrations?** Batch through `api/asset`, page
without totals, pin one upper time bound per run, and read
[extracting at scale](/guides/query-size-and-performance#extracting-at-scale-full-loads-and-delta-sync)
before you start.

**How do I test without touching production?** Ask your administrator
about a test instance — and remember deletes are
[recoverable until purged](/concepts/operations#the-lifecycle-quartet),
which softens mistakes but is not a sandbox.

## Related Topics

- [Troubleshooting by symptom](/troubleshooting)
- [Getting started](/getting-started/quickstart)
- [Choosing an API](/getting-started/choosing-an-api)