# Agent Effectiveness API
Agent Effectiveness API: pull cost attribution out of Factory with the Analytics API, Factory Standard Credits per session, pull request, ticket, and project from /sessions, /prs, /tickets, and /projects, and how to use the rows without double counting.
Use the [Analytics API](/api-reference/analytics) to pull cost attribution for your work: how much agent spend went into each pull request, ticket, project, or session, sliced by repository, project, user, date range, or state, so you can build your own ROI reporting.
The Agent Effectiveness API is in Private Preview with limited availability. Contact your Factory account team to request access.
---
## What you can pull
| Route | One row per | Each row carries |
| :----------------------------------------------------- | :------------------------------------- | :-------------------------------------------------------------------------- |
| [`/sessions`](/api-reference/analytics#sessions) | Root session, sub-agents folded in | Owner, lifetime Factory Standard Credits, primary intent, linked issues and pull requests |
| [`/prs`](/api-reference/analytics#pull-requests) | Pull request | State and timestamps, line statistics, author, attributed sessions and credits |
| [`/tickets`](/api-reference/analytics#tickets) | Linear issue or Jira issue | State, estimate, assignee, parent, project, attributed sessions and credits |
| [`/projects`](/api-reference/analytics#projects) | Linear project or Jira epic | State, dates, linked ticket count, attributed sessions and credits |
Attribution on a pull request, ticket, or project is the set of root sessions that linked it. Its credits are the sum of those sessions' lifetime Factory Standard Credits; a session that linked three items counts fully under each.
---
## What you need
Enterprise with the Advanced Analytics enterprise control turned on. See
[Enable Agent Effectiveness](/agent-effectiveness/setup).
An API key created by an Owner or Manager, or a service-account key. Keys that
Factory issues to computers and sandboxes are refused.
Private Preview enablement for your organization. The routes return `403` until Factory
enables the Agent Effectiveness API for yours. [Contact support](mailto:support@factory.com) to request access.
---
## Example
Pull requests merged or closed in October with at least one attributed session:
```bash
curl -H "Authorization: Bearer $FACTORY_API_KEY" \
"https://api.factory.ai/api/v1/analytics/prs?startDate=2026-10-01&endDate=2026-10-31&attributed=true&limit=500"
```
Every route returns `{ data, meta }`. Follow `meta.next_cursor` until `meta.has_more` is `false`. A window can span up to 366 days.
---
## Using the data
- A row's `factory_standard_credits` is the lifetime spend of every root session that linked it, each counted in full. It is a cost for that item, not a share of organization spend.
- Never sum `factory_standard_credits` across rows of one route, or across routes, to get total spend. A session that linked three items counts fully under each, and a project already includes the sessions linked through its tickets or directly to it. Use [`/tokens`](/api-reference/analytics#factory-standard-credits-usage) for totals.
- To cost a set of items without double counting, union their `root_session_ids` and sum each session once from [`/sessions`](/api-reference/analytics#sessions). A row with `session_ids_truncated: true` lists only 500 roots.
- Measure coverage with `attributed=true` and `attributed=false` (or `linked=` on `/sessions`). An unattributed item had no session link it; its credits are `0`.
- Windows differ by route: `/prs` selects on `state_at`, `/tickets` and `/projects` on `date_basis`, `/sessions` on the root's `completed_at`. `/sessions` summed over a window is lifetime spend of the sessions that completed in it, so it does not tie to `/tokens` for the same dates. See [Using the data](/api-reference/analytics#using-the-data) for the full rules.
---
## How rows join
| From | To | Key |
| :------------------------------------------------------------------------- | :----------------------------------------------------------------- | :--------------------------------------------------------------- |
| `/prs` `url` | `/sessions` `pull_requests[].url` | Canonical pull request URL |
| `/tickets` `url`, `key` | `/sessions` `issues[].url`, `issue_key=` | Issue URL, issue key |
| `/tickets` `project.url` | `/projects` `url` | Container URL |
| `attribution.root_session_ids[]` | `/sessions` `session_id` | Root session id |
| `attribution.contributor_user_ids[]`, `author.user_id`, `assignee.user_id` | `/sessions` `owner_user_id`, [`/users`](/api-reference/analytics#per-user-metrics) `user_id` | Factory user id (`null` while the provider identity is unlinked) |
Authentication, pagination, filters, terms, and errors shared by these routes.
Control spend and measure what it produces.
Connect integrations and turn on Advanced Analytics.
The same attribution data in the Factory App.