List projects

GET https://app.honeybadger.io/v3/projects

Required scope projects:read

Returns a list of projects for the account.

Example request

curl "https://app.honeybadger.io/v3/projects" \
  -H "Authorization: Bearer $HONEYBADGER_API_TOKEN"

Parameters

Query parameters

Field	Type	Description
`name`	string	Exact project name to match. Omit or leave blank to list all accessible projects.
`page`	integer	Page number (1-indexed). Default: `1`. Min 1.
`per_page`	integer	Items per page. Default: `25`. Min 1, max 100.

Responses

200 Success

Example payload

{
  "data": [
    {
      "id": "Xk9mZp",
      "account_id": "Ab3kL9",
      "name": "My Rails App",
      "active": true,
      "disable_public_links": true,
      "environments": [
        "production",
        "staging",
        "development"
      ],
      "resolve_errors_on_deploy": true,
      "user_url": "https://admin.example.com/users/[user_id]",
      "source_url": "https://github.com/acme/app/blob/main/[file]#L[line]",
      "user_search_field": "context.account_id",
      "asana_workspace_id": null,
      "customer_throttle": 0,
      "language": "Ruby",
      "fault_count": 128,
      "unresolved_fault_count": 12,
      "last_notice_at": "2026-01-01T00:00:00Z",
      "earliest_notice_at": "2026-01-01T00:00:00Z",
      "purge_days": 90,
      "created_at": "2026-01-01T00:00:00Z",
      "links": {
        "web": "https://app.honeybadger.io/projects/Xk9mZp"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25
  },
  "links": {
    "self": "/v3/projects?page=2&per_page=25",
    "first": "/v3/projects?page=1&per_page=25",
    "prev": "/v3/projects?page=1&per_page=25",
    "next": "/v3/projects?page=3&per_page=25"
  },
  "meta": {
    "request_id": "6f1c2b0e-8d4a-4f6e-9b2a-3c5d7e9f1a2b"
  }
}

Response schema32

Field	Type	Description
`data` required	array<object>
`data[].id` required	string
`data[].account_id` required	string	ID of the account this project belongs to.
`data[].name` required	string	Project name.
`data[].active` required	boolean	Whether the project is active.
`data[].disable_public_links` required	boolean	Whether public error links are disabled.
`data[].environments` required	array<string>	List of environment names seen in this project.
`data[].resolve_errors_on_deploy` required	boolean	Whether recording a deploy resolves every open fault.
`data[].user_url` required	string \| null	Template linking a fault's affected user into your own system. `[user_id]` and `[user_email]` are substituted.
`data[].source_url` required	string \| null	Template linking a backtrace line to your source host. `[file]` and `[line]` are substituted.
`data[].user_search_field` required	string \| null	Context key identifying the affected user, when it is not in the default `context.user_email` or `context.user_id`.
`data[].asana_workspace_id` required	string \| null	Asana workspace used by the project's Asana integration.
`data[].customer_throttle` required	integer \| null	Notices accepted per minute before throttling kicks in.
`data[].language` required	string \| null	Primary programming language.
`data[].fault_count` required	integer	Total number of faults (errors) in this project.
`data[].unresolved_fault_count` required	integer	Number of unresolved faults.
`data[].last_notice_at` required	date-time \| null	When the last error was received.
`data[].earliest_notice_at` required	date-time \| null	The start of the retention window: now minus the project's `purge_days` (or the account's retention when unset), at most 180 days. Computed on each read, so it moves forward with the clock.
`data[].purge_days` required	integer \| null	Data retention period in days.
`data[].created_at` required	date-time	When the project was created.
`data[].links` required	object	Links into the Honeybadger web UI.
`data[].links.web` required	uri	The resource's page in the Honeybadger web UI, as an absolute URL. Resources without a page, such as outages and deploys, don't have `links`. For a project provisioned through Heroku, error, notice and comment links go through Heroku's single sign-on.
`pagination`	object	Offset-based pagination information.
`pagination.page` required	integer	Current page number. Min 1.
`pagination.per_page` required	integer	Items per page. Min 1, max 100.
`links`	object	Navigation links for a numbered-page collection. Each link is a root-relative path (`/v3/...`); resolve it against the API host.
`links.self` required	uri-reference	This page.
`links.first`	uri-reference	First page.
`links.prev`	string \| null	Previous page, or null on the first page.
`links.next`	string \| null	Next page, or null on the last page.
`meta`	object
`meta.request_id`	string	Unique identifier for the request, for correlating with support.

Errors

400 Bad Request

A query parameter is malformed or outside its allowed values. error.details names the parameter.

Example payload

{
  "error": {
    "code": "invalid_parameter",
    "message": "unmapped must be true or false",
    "details": [
      {
        "field": "unmapped",
        "message": "must be true or false"
      }
    ]
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
`error` required	object
`error.code` required	string	Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`.
`error.message` required	string	Human-readable explanation.
`error.details`	array<object> \| object	A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add.
`meta`	object
`meta.request_id`	string	Unique identifier for the request, for correlating with support.

401 Unauthorized

The credential is missing, invalid, expired or revoked (unauthorized), or was sent in a way v3 doesn’t accept (see the examples).

Example payload: unauthorized (Missing, malformed, expired or revoked credential)

{
  "error": {
    "code": "unauthorized",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: unsupported_auth_scheme (Sent as HTTP basic, which v3 does not accept)

{
  "error": {
    "code": "unsupported_auth_scheme",
    "message": "Send the credential as `Authorization: Bearer <token>`; v3 does not accept HTTP basic"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: credential_in_query (Sent as the `auth_token` query parameter)

{
  "error": {
    "code": "credential_in_query",
    "message": "Credentials must be sent in the Authorization header"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
`error` required	object
`error.code` required	string	Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`.
`error.message` required	string	Human-readable explanation.
`error.details`	array<object> \| object	A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add.
`meta`	object
`meta.request_id`	string	Unique identifier for the request, for correlating with support.

403 Forbidden

The credential isn’t allowed to do this. error.code says why. An account or project the credential doesn’t cover is 404 not_found, not 403.

Example payload: access_denied (The credential isn't allowed to do this to this record)

{
  "error": {
    "code": "access_denied",
    "message": "Access denied"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: insufficient_scope (The credential lacks the permission this endpoint requires)

{
  "error": {
    "code": "insufficient_scope",
    "message": "Insufficient scope",
    "details": {
      "required_scope": "faults:write",
      "token_scopes": [
        "faults:read",
        "insights:read"
      ]
    }
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: requires_user_token (The endpoint records who acted, and an account token has nobody)

{
  "error": {
    "code": "requires_user_token",
    "message": "This endpoint records the person who acted, so it requires a user credential rather than an account token"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Example payload: project_restricted (A project-restricted credential cannot create a project)

{
  "error": {
    "code": "project_restricted",
    "message": "Project-restricted tokens cannot create projects"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
`error` required	object
`error.code` required	string	Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`.
`error.message` required	string	Human-readable explanation.
`error.details`	array<object> \| object	A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add.
`meta`	object
`meta.request_id`	string	Unique identifier for the request, for correlating with support.

404 Not Found

Resource not found

Example payload

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
`error` required	object
`error.code` required	string	Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`.
`error.message` required	string	Human-readable explanation.
`error.details`	array<object> \| object	A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add.
`meta`	object
`meta.request_id`	string	Unique identifier for the request, for correlating with support.

422 Unprocessable Content

No path names the account, so the API token has to. This is returned when the token covers more than one account and the account a request applies to cannot be determined. Use a token bound to a single account.

Example payload

{
  "error": {
    "code": "ambiguous_account",
    "message": "This credential covers more than one account, so the account a request applies to is ambiguous. Use a token bound to a single account."
  },
  "meta": {
    "request_id": "abc123"
  }
}

Response schema6

Field	Type	Description
`error` required	object
`error.code` required	string	Machine-readable code. Branch on this, not the message. Allowed values: `unauthorized`, `unsupported_auth_scheme`, `credential_in_query`, `access_denied`, `insufficient_scope`, `requires_user_token`, `project_restricted`, `account_inactive`, `account_parked`, `feature_unavailable`, `not_found`, `validation_error`, `delete_failed`, `limit_reached`, `rate_limit_exceeded`, `concurrent_request`, `streams_provisioning`, `ingestion_key_not_accepted`, `maintenance_mode`, `invalid_parameter`, `forbidden_attributes`, `service_unavailable`, `ambiguous_account`, `fault_merged`.
`error.message` required	string	Human-readable explanation.
`error.details`	array<object> \| object	A list of `{field, message}` on `validation_error` and `invalid_parameter`, and on `feature_unavailable` or `limit_reached` when one field caused the refusal; `{required_scope, token_scopes}` on `insufficient_scope`; `{merged_into, location}` on `fault_merged`. Absent when there's nothing to add.
`meta`	object
`meta.request_id`	string	Unique identifier for the request, for correlating with support.