Agent Effectiveness API

Private Preview

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 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.

Private Preview

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`	Root session, sub-agents folded in	Owner, lifetime Factory Standard Credits, primary intent, linked issues and pull requests
`/prs`	Pull request	State and timestamps, line statistics, author, attributed sessions and credits
`/tickets`	Linear issue or Jira issue	State, estimate, assignee, parent, project, attributed sessions and credits
`/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

Plan: Enterprise with the Advanced Analytics enterprise control turned on. See Enable Agent Effectiveness.
Credential: An API key created by an Owner or Manager, or a service-account key. Keys that Factory issues to computers and sandboxes are refused.
Enablement: Private Preview enablement for your organization. The routes return 403 until Factory enables the Agent Effectiveness API for yours. Contact support 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 for totals.
To cost a set of items without double counting, union their root_session_ids and sum each session once from /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 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` `user_id`	Factory user id (`null` while the provider identity is unlinked)

Related resources

Analytics API

Authentication, pagination, filters, terms, and errors shared by these routes.

Cost & Productivity

Control spend and measure what it produces.

Enable Agent Effectiveness

Connect integrations and turn on Advanced Analytics.

Effectiveness Dashboard

The same attribution data in the Factory App.