Agent Trace permissions
Last updated: October 27, 2026
Span controls who can see agent traces, their contents, and trace-based reports with four Agent Trace permissions, which you grant to people through permission groups.
Why it matters
Different people need different views of AI coding activity. An engineer wants to review their own sessions. A team lead wants cost and evaluation trends for the team. A platform team wants Harness health recommendations without reading anyone's prompts. Agent Trace permissions let you give each of them exactly that, down to the person.
For admins: decide who sees trace facts, who can read trace contents, and who can delete traces.
For engineers: by default, nobody but you can read your prompts and transcripts.
How it works
The four permissions
Permission | What it allows | Granted for |
|---|---|---|
Agent Trace Data | Trace metadata: the trace list, cost and model usage, duration and activity counts, evaluation scores, and rolled-up trace metrics. It unlocks the pages built on that metadata, such as the AI Effectiveness Overview, Traces, and AI investment. | Teams or individuals |
Agent Trace Contents | The trace itself: prompts, agent responses, tool calls, and the turn-by-turn transcript. It also reveals metadata generated from the session: the trace title, the evaluation summary, and the reasoning and citations behind each score. Applies only when your organization uses permission-based trace contents (see below). | Individuals only, together with Agent Trace Data for the same people |
Agent Trace Reporting | The insights layer built on traces, including the Harness health page (formerly Environment Readiness) and its recommendations. | Teams or individuals |
Manage Traces | Delete traces. Deleting a trace also removes any linked sub-sessions captured as part of it. | Individuals only, together with Agent Trace Data for the same people |
Each permission is scoped: you grant it for specific people or teams, not org-wide. Someone with a trace permission sees traces belonging to the people and teams they were granted, not everything in the organization.
Agent Trace Data excludes anything generated from the session. Prompts, conversations, evaluation summaries, the reasoning behind each score, and trace titles can all reveal what was said in a session, so Agent Trace Data never includes them. Traces appear in the list with a placeholder name, such as Trace #0a1b2c, instead of their title.
Agent Trace Reporting is independent. On its own, it shows Harness health recommendations but not the traces behind them. Pair it with Agent Trace Data if people should be able to drill from a recommendation into the sessions that produced it.
Two ways to handle trace contents
Author-only (default): only the engineer who ran a session can read its prompts, transcript, title, and score reasoning. Agent Trace Contents has no effect. Everyone else with Agent Trace Data sees the trace marked Only visible to author.
Permission-based: if your organization wants named people to read trace contents, Span switches your organization to this mode on request. Then anyone, including a trace's author, needs both Agent Trace Data and Agent Trace Contents for a person to read that person's trace contents. People without them see You don't have permission to view this.
Both are valid choices. Some organizations keep sessions private to the engineer; others want leads to read sessions for coaching. Trace Screening restricts sensitive sessions to their author in either mode.
Default permission groups
Permission group | Agent Trace permissions out of the box |
|---|---|
Owners | All four, for everyone |
Admins | All four, for everyone |
Team Leads | None |
Managers (assigned automatically to everyone who manages people) | None |
Team Members (assigned to everyone) | None |
Because only Owners and Admins start with trace permissions, engineers can't open the Traces page, even for their own sessions, until you add Agent Trace Data to their permission group.
Setup
People with the Manage Permission Groups permission (Owners, by default) can change permission groups.
Go to Settings → Permission Groups.
Open the group you want to change, or click Add group.
Grant trace permissions in the matching step:
Self Permissions: what members see about themselves. Add Agent Trace Data so engineers can see their own traces.
People Permissions: which individuals' data members can see. Choose Reports, Reports & Team Members, Specific Teams, or All People.
Teams Permissions: which teams' aggregated data members can see. Choose Affiliated Teams, Specific Teams, or All Teams.
Review and save.
Common setups by role
Individual contributors (own traces only): in Team Members, add Agent Trace Data under Self Permissions.
Team leads (their team's trace facts): in Team Leads, add Agent Trace Data under People Permissions for Reports & Team Members, and under Teams Permissions for Affiliated Teams.
Managers (their reports' trace facts and recommendations): in Managers, add Agent Trace Data and Agent Trace Reporting under People Permissions for Reports.
Observers, such as a platform team: create a group with Agent Trace Reporting only, so they see Harness health recommendations without individual traces.
Reading other people's trace contents: ask Span to switch your organization to permission-based trace contents, then grant Agent Trace Contents to named individuals for named people. Remember to also grant Agent Trace Contents under Self Permissions, so engineers can still read their own sessions.
Troubleshooting
An engineer gets an access error (403) on the Traces page, or doesn't see it in the menu. Their permission groups don't include Agent Trace Data, even for themselves. Add it under Self Permissions in a group they belong to, such as Team Members. If no one in your organization sees the page and Span shows "Trace processing is not enabled", ask your Span account team to turn on trace processing.
A lead sees their own traces but not their team's. Their group grants Agent Trace Data under Self Permissions only. Add it under People Permissions for the right people.
Traces show "Only visible to author". This is expected under the default author-only policy. Only the author can read those contents.
Traces show "You don't have permission to view this". Your organization uses permission-based trace contents, and the viewer lacks Agent Trace Contents for that person.
Someone can't open Settings → Traces to get the traces token. That page needs admin access or the permission to manage integrations, which the Integration Admins group has.
An engineer with Agent Trace Data still sees none of their own traces. Span links each session to a person by the work email on the device. If that email doesn't match the email on their Span profile, their sessions count in organization totals but don't appear under their name. Check the email auspex reports with
auspex auth show.Checking one person's access. Open the person's profile and select the Permissions tab to see every permission their groups grant. This tab needs the Manage Permission Groups permission.
Things to know
Scores are facts; reasoning is content. People with Agent Trace Data see evaluation scores, but only people who can read a trace's contents see the reasoning behind them.
Worked example. A manager has Agent Trace Data for her 8 reports under the default policy. She sees each report's sessions, cost, models, and evaluation scores, all under placeholder names. She can't read any report's prompts or score reasoning. She sees her own traces only if her group also grants Agent Trace Data under Self Permissions.
Screening outranks permissions. A screened trace's contents stay private to its author, even for people with Agent Trace Contents.
Deleting is permanent. Manage Traces deletes the trace and its linked sub-sessions.
Related articles
Need help?
Contact your Span account team or reach out to support@span.app.