> ## Documentation Index > Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code. > Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer. > For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them. > The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes. # List Developer traces > Returns root Span summaries in Timestamp and TraceId descending order. The from/to range uses RFC 3339 timestamps at millisecond precision. Keep the range and filters fixed while incrementing offset; no total or page token is calculated. ## OpenAPI ````yaml https://api.photon.codes/openapi.json get /v1/projects/{projectId}/developer/otel/traces openapi: 3.1.0 info: title: Photon API version: 1.0.0 servers: - url: https://api.photon.codes security: [] paths: /v1/projects/{projectId}/developer/otel/traces: get: tags: - Developer OTel summary: List Developer traces description: >- Returns root Span summaries in Timestamp and TraceId descending order. The from/to range uses RFC 3339 timestamps at millisecond precision. Keep the range and filters fixed while incrementing offset; no total or page token is calculated. operationId: listDeveloperTraces parameters: - in: path name: projectId required: true schema: type: string - description: >- RFC 3339 timestamp with at most three fractional digits (millisecond precision). in: query name: from required: true schema: format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ type: string - description: >- RFC 3339 timestamp with at most three fractional digits (millisecond precision). in: query name: to required: true schema: format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ type: string - in: query name: requestId schema: maxLength: 128 minLength: 1 type: string - in: query name: apiKeyId schema: maxLength: 128 minLength: 1 type: string - in: query name: route schema: maxLength: 512 minLength: 1 type: string - in: query name: httpMethod schema: pattern: ^[A-Z]{1,32}$ type: string - in: query name: httpStatusCode schema: maximum: 599 minimum: 100 type: integer - in: query name: httpStatusClass schema: enum: - 1xx - 2xx - 3xx - 4xx - 5xx type: string - in: query name: status schema: enum: - Ok - Error - Unset type: string - in: query name: type schema: enum: - request - delivery type: string - in: query name: minimumDurationMs schema: maximum: 18446744073709 minimum: 0 type: integer - in: query name: limit schema: maximum: 100 minimum: 1 type: integer - in: query name: offset schema: maximum: 1000000 minimum: 0 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListDeveloperTracesResponse' description: A bounded page of Developer trace summaries. headers: Deprecation: $ref: '#/components/headers/Deprecation' Idempotent-Replayed: $ref: '#/components/headers/Idempotent-Replayed' Link: $ref: '#/components/headers/Link' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Retry-After: $ref: '#/components/headers/Retry-After' Sunset: $ref: '#/components/headers/Sunset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' '400': content: application/problem+json: schema: $ref: '#/components/schemas/ListDeveloperTracesBadRequestProblem' description: >- INVALID_ARGUMENT: Invalid Argument; INVALID_QUERY: Invalid Developer OTel Query; FORBIDDEN_SQL: Forbidden Developer OTel SQL; INVALID_PARAMETER: Invalid Developer OTel Query Parameter headers: Deprecation: $ref: '#/components/headers/Deprecation' Idempotent-Replayed: $ref: '#/components/headers/Idempotent-Replayed' Link: $ref: '#/components/headers/Link' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Retry-After: $ref: '#/components/headers/Retry-After' Sunset: $ref: '#/components/headers/Sunset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' '401': content: application/problem+json: schema: $ref: '#/components/schemas/NotAuthenticatedProblem' description: 'NOT_AUTHENTICATED: Not Authenticated' headers: Link: description: Optional related resources. schema: type: string RateLimit: description: Optional rate limit information. schema: type: string RateLimit-Policy: description: Optional rate limit policy. schema: type: string Retry-After: description: Optional retry delay or HTTP date. schema: type: string WWW-Authenticate: required: true schema: type: string X-Request-ID: description: Application request identifier. schema: type: string '403': content: application/problem+json: schema: $ref: '#/components/schemas/ListDeveloperTracesForbiddenProblem' description: >- FORBIDDEN: Forbidden; RESOURCE_MISMATCH: Resource Mismatch FORBIDDEN: Forbidden; INSUFFICIENT_SCOPE: Insufficient Scope; ORGANIZATION_SSO_REQUIRED: Organization SSO Required headers: Deprecation: description: >- RFC 9745 structured-field Date at which the operation was or will be deprecated: `@` followed by Unix seconds, for example `@1767225599`. schema: pattern: ^@-?[0-9]+$ type: string Idempotent-Replayed: description: True when this response was replayed from an earlier attempt. schema: type: boolean Link: description: |- Links related to lifecycle or remediation documentation. Optional related resources. schema: type: string RateLimit: description: |- Current rate-limit state. Optional rate limit information. schema: type: string RateLimit-Policy: description: |- Rate-limit policy applied by the gateway. Optional rate limit policy. schema: type: string Retry-After: description: |- Delay before retrying, in seconds or as an HTTP date. Optional retry delay or HTTP date. schema: type: string Sunset: description: >- RFC 8594 HTTP-date (IMF-fixdate) after which the operation may become unavailable, for example `Thu, 31 Dec 2026 23:59:59 GMT`. schema: pattern: >- ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$ type: string X-Request-ID: description: |- Identifier for this HTTP attempt. Application request identifier. schema: type: string X-Trace-ID: description: >- Trace ID of this request. Sent alongside X-Request-ID when a middleware published a trace ID for the request. schema: pattern: ^(?!0{32}$)[0-9a-f]{32}$ type: string '413': content: application/problem+json: schema: $ref: '#/components/schemas/PayloadTooLargeProblem' description: 'PAYLOAD_TOO_LARGE: Payload Too Large' headers: Deprecation: $ref: '#/components/headers/Deprecation' Idempotent-Replayed: $ref: '#/components/headers/Idempotent-Replayed' Link: $ref: '#/components/headers/Link' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Retry-After: $ref: '#/components/headers/Retry-After' Sunset: $ref: '#/components/headers/Sunset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' '422': content: application/problem+json: schema: $ref: >- #/components/schemas/ListDeveloperTracesUnprocessableEntityProblem description: >- VALIDATION_FAILED: Request Validation Failed; RESOURCE_LIMIT: Developer OTel Query Resource Limit headers: Deprecation: $ref: '#/components/headers/Deprecation' Idempotent-Replayed: $ref: '#/components/headers/Idempotent-Replayed' Link: $ref: '#/components/headers/Link' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Retry-After: $ref: '#/components/headers/Retry-After' Sunset: $ref: '#/components/headers/Sunset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' '429': content: application/problem+json: schema: $ref: '#/components/schemas/QueryConcurrencyLimitProblem' description: 'QUERY_CONCURRENCY_LIMIT: Query Concurrency Limit' headers: Deprecation: $ref: '#/components/headers/Deprecation' Idempotent-Replayed: $ref: '#/components/headers/Idempotent-Replayed' Link: $ref: '#/components/headers/Link' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Retry-After: $ref: '#/components/headers/Retry-After' Sunset: $ref: '#/components/headers/Sunset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' '500': content: application/problem+json: schema: $ref: >- #/components/schemas/ListDeveloperTracesInternalServerErrorProblem description: |- INVALID_AUTH_CONTEXT: Invalid Authentication Context INTERNAL_ERROR: Internal Server Error headers: Deprecation: description: >- RFC 9745 structured-field Date at which the operation was or will be deprecated: `@` followed by Unix seconds, for example `@1767225599`. schema: pattern: ^@-?[0-9]+$ type: string Idempotent-Replayed: description: True when this response was replayed from an earlier attempt. schema: type: boolean Link: description: |- Links related to lifecycle or remediation documentation. Optional related resources. schema: type: string RateLimit: description: |- Current rate-limit state. Optional rate limit information. schema: type: string RateLimit-Policy: description: |- Rate-limit policy applied by the gateway. Optional rate limit policy. schema: type: string Retry-After: description: |- Delay before retrying, in seconds or as an HTTP date. Optional retry delay or HTTP date. schema: type: string Sunset: description: >- RFC 8594 HTTP-date (IMF-fixdate) after which the operation may become unavailable, for example `Thu, 31 Dec 2026 23:59:59 GMT`. schema: pattern: >- ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$ type: string X-Request-ID: description: |- Identifier for this HTTP attempt. Application request identifier. schema: type: string X-Trace-ID: description: >- Trace ID of this request. Sent alongside X-Request-ID when a middleware published a trace ID for the request. schema: pattern: ^(?!0{32}$)[0-9a-f]{32}$ type: string '502': content: application/problem+json: schema: $ref: '#/components/schemas/ListDeveloperTracesBadGatewayProblem' description: >- UPSTREAM_FAILURE: Upstream Service Failure; EXECUTION_FAILED: Developer OTel Query Execution Failed headers: Deprecation: $ref: '#/components/headers/Deprecation' Idempotent-Replayed: $ref: '#/components/headers/Idempotent-Replayed' Link: $ref: '#/components/headers/Link' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Retry-After: $ref: '#/components/headers/Retry-After' Sunset: $ref: '#/components/headers/Sunset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' '503': content: application/problem+json: schema: $ref: '#/components/schemas/UpstreamUnavailableProblem' description: 'UPSTREAM_UNAVAILABLE: Upstream Service Unavailable' headers: Deprecation: description: >- RFC 9745 structured-field Date at which the operation was or will be deprecated: `@` followed by Unix seconds, for example `@1767225599`. schema: pattern: ^@-?[0-9]+$ type: string Idempotent-Replayed: description: True when this response was replayed from an earlier attempt. schema: type: boolean Link: description: |- Links related to lifecycle or remediation documentation. Optional related resources. schema: type: string RateLimit: description: |- Current rate-limit state. Optional rate limit information. schema: type: string RateLimit-Policy: description: |- Rate-limit policy applied by the gateway. Optional rate limit policy. schema: type: string Retry-After: description: |- Delay before retrying, in seconds or as an HTTP date. Optional retry delay or HTTP date. schema: type: string Sunset: description: >- RFC 8594 HTTP-date (IMF-fixdate) after which the operation may become unavailable, for example `Thu, 31 Dec 2026 23:59:59 GMT`. schema: pattern: >- ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$ type: string X-Request-ID: description: |- Identifier for this HTTP attempt. Application request identifier. schema: type: string X-Trace-ID: description: >- Trace ID of this request. Sent alongside X-Request-ID when a middleware published a trace ID for the request. schema: pattern: ^(?!0{32}$)[0-9a-f]{32}$ type: string '504': content: application/problem+json: schema: $ref: '#/components/schemas/ListDeveloperTracesGatewayTimeoutProblem' description: >- UPSTREAM_TIMEOUT: Upstream Service Timeout; REQUEST_TIMEOUT: Request Timeout; TIMEOUT: Developer OTel Query Timeout headers: Deprecation: $ref: '#/components/headers/Deprecation' Idempotent-Replayed: $ref: '#/components/headers/Idempotent-Replayed' Link: $ref: '#/components/headers/Link' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Retry-After: $ref: '#/components/headers/Retry-After' Sunset: $ref: '#/components/headers/Sunset' X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-Trace-ID: $ref: '#/components/headers/X-Trace-ID' security: - accountServiceKey: [] - projectApiKey: [] - oauth2: - project:read components: schemas: ListDeveloperTracesResponse: additionalProperties: false properties: traces: items: additionalProperties: false properties: rootSpan: additionalProperties: false properties: attributes: items: $ref: '#/components/schemas/OtlpKeyValue' type: array droppedAttributesCount: maximum: 9007199254740991 minimum: 0 type: integer droppedEventsCount: maximum: 9007199254740991 minimum: 0 type: integer droppedLinksCount: maximum: 9007199254740991 minimum: 0 type: integer endTimeUnixNano: pattern: ^[0-9]+$ type: string events: items: additionalProperties: false properties: attributes: items: $ref: '#/components/schemas/OtlpKeyValue' type: array droppedAttributesCount: maximum: 9007199254740991 minimum: 0 type: integer name: type: string timeUnixNano: pattern: ^[0-9]+$ type: string required: - attributes - name - timeUnixNano type: object type: array flags: maximum: 9007199254740991 minimum: 0 type: integer kind: maximum: 9007199254740991 minimum: 0 type: integer links: items: additionalProperties: false properties: attributes: items: $ref: '#/components/schemas/OtlpKeyValue' type: array droppedAttributesCount: maximum: 9007199254740991 minimum: 0 type: integer flags: maximum: 9007199254740991 minimum: 0 type: integer spanId: maxLength: 16 minLength: 16 pattern: ^[0-9a-f]+$ type: string traceId: maxLength: 32 minLength: 32 pattern: ^[0-9a-f]+$ type: string traceState: type: string required: - attributes - spanId - traceId type: object type: array name: type: string parentSpanId: maxLength: 16 minLength: 16 pattern: ^[0-9a-f]+$ type: string spanId: maxLength: 16 minLength: 16 pattern: ^[0-9a-f]+$ type: string startTimeUnixNano: pattern: ^[0-9]+$ type: string status: additionalProperties: false properties: code: maximum: 9007199254740991 minimum: 0 type: integer message: type: string required: - code type: object traceId: maxLength: 32 minLength: 32 pattern: ^[0-9a-f]+$ type: string traceState: type: string required: - attributes - endTimeUnixNano - events - kind - links - name - spanId - startTimeUnixNano - traceId type: object traceId: maxLength: 32 minLength: 32 pattern: ^[0-9a-f]+$ type: string required: - rootSpan - traceId type: object type: array required: - traces type: object ListDeveloperTracesBadRequestProblem: oneOf: - $ref: '#/components/schemas/InvalidArgumentProblem' - $ref: '#/components/schemas/InvalidQueryProblem' - $ref: '#/components/schemas/ForbiddenSqlProblem' - $ref: '#/components/schemas/InvalidParameterProblem' NotAuthenticatedProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: NOT_AUTHENTICATED status: 401 title: Not Authenticated type: https://photon.codes/docs/problems/not-authenticated properties: code: const: NOT_AUTHENTICATED type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 401 type: number title: const: Not Authenticated type: string type: const: https://photon.codes/docs/problems/not-authenticated type: string required: - code - status - title - type type: object ListDeveloperTracesForbiddenProblem: oneOf: - $ref: '#/components/schemas/ForbiddenProblem' - $ref: '#/components/schemas/InsufficientScopeProblem' - $ref: '#/components/schemas/OrganizationSsoRequiredProblem' - $ref: '#/components/schemas/ResourceMismatchProblem' PayloadTooLargeProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: PAYLOAD_TOO_LARGE status: 413 title: Payload Too Large type: https://photon.codes/docs/problems/payload-too-large properties: code: const: PAYLOAD_TOO_LARGE type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 413 type: number title: const: Payload Too Large type: string type: const: https://photon.codes/docs/problems/payload-too-large type: string required: - code - status - title - type type: object ListDeveloperTracesUnprocessableEntityProblem: oneOf: - $ref: '#/components/schemas/ValidationFailedProblem' - $ref: '#/components/schemas/ResourceLimitProblem' QueryConcurrencyLimitProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: QUERY_CONCURRENCY_LIMIT status: 429 title: Query Concurrency Limit type: https://photon.codes/docs/problems/query-concurrency-limit properties: code: const: QUERY_CONCURRENCY_LIMIT type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 429 type: number title: const: Query Concurrency Limit type: string type: const: https://photon.codes/docs/problems/query-concurrency-limit type: string required: - code - status - title - type type: object ListDeveloperTracesInternalServerErrorProblem: oneOf: - $ref: '#/components/schemas/InternalErrorProblem' - $ref: '#/components/schemas/InvalidAuthContextProblem' ListDeveloperTracesBadGatewayProblem: oneOf: - $ref: '#/components/schemas/UpstreamFailureProblem' - $ref: '#/components/schemas/ExecutionFailedProblem' UpstreamUnavailableProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: UPSTREAM_UNAVAILABLE status: 503 title: Upstream Service Unavailable type: https://photon.codes/docs/problems/upstream-unavailable properties: code: const: UPSTREAM_UNAVAILABLE type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 503 type: number title: const: Upstream Service Unavailable type: string type: const: https://photon.codes/docs/problems/upstream-unavailable type: string required: - code - status - title - type type: object ListDeveloperTracesGatewayTimeoutProblem: oneOf: - $ref: '#/components/schemas/UpstreamTimeoutProblem' - $ref: '#/components/schemas/RequestTimeoutProblem' - $ref: '#/components/schemas/TimeoutProblem' OtlpKeyValue: additionalProperties: false properties: key: type: string value: $ref: '#/components/schemas/OtlpAnyValue' required: - key type: object InvalidArgumentProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: INVALID_ARGUMENT status: 400 title: Invalid Argument type: https://photon.codes/docs/problems/invalid-argument properties: code: const: INVALID_ARGUMENT type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 400 type: number title: const: Invalid Argument type: string type: const: https://photon.codes/docs/problems/invalid-argument type: string required: - code - status - title - type type: object InvalidQueryProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: INVALID_QUERY status: 400 title: Invalid Developer OTel Query type: https://photon.codes/docs/problems/developer-otel-invalid-query properties: code: const: INVALID_QUERY type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 400 type: number title: const: Invalid Developer OTel Query type: string type: const: https://photon.codes/docs/problems/developer-otel-invalid-query type: string required: - code - status - title - type type: object ForbiddenSqlProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: FORBIDDEN_SQL status: 400 title: Forbidden Developer OTel SQL type: https://photon.codes/docs/problems/developer-otel-forbidden-sql properties: code: const: FORBIDDEN_SQL type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 400 type: number title: const: Forbidden Developer OTel SQL type: string type: const: https://photon.codes/docs/problems/developer-otel-forbidden-sql type: string required: - code - status - title - type type: object InvalidParameterProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: INVALID_PARAMETER status: 400 title: Invalid Developer OTel Query Parameter type: https://photon.codes/docs/problems/developer-otel-invalid-parameter properties: code: const: INVALID_PARAMETER type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 400 type: number title: const: Invalid Developer OTel Query Parameter type: string type: const: https://photon.codes/docs/problems/developer-otel-invalid-parameter type: string required: - code - status - title - type type: object JsonValue: anyOf: - type: string - type: number - type: boolean - type: 'null' - items: $ref: '#/components/schemas/JsonValue' type: array - additionalProperties: $ref: '#/components/schemas/JsonValue' propertyNames: type: string type: object ForbiddenProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: FORBIDDEN status: 403 title: Forbidden type: https://photon.codes/docs/problems/forbidden properties: code: const: FORBIDDEN type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 403 type: number title: const: Forbidden type: string type: const: https://photon.codes/docs/problems/forbidden type: string required: - code - status - title - type type: object InsufficientScopeProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: INSUFFICIENT_SCOPE status: 403 title: Insufficient Scope type: https://photon.codes/docs/problems/insufficient-scope properties: code: const: INSUFFICIENT_SCOPE type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 403 type: number title: const: Insufficient Scope type: string type: const: https://photon.codes/docs/problems/insufficient-scope type: string required: - code - status - title - type type: object OrganizationSsoRequiredProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: ORGANIZATION_SSO_REQUIRED status: 403 title: Organization SSO Required type: https://photon.codes/docs/problems/organization-sso-required properties: code: const: ORGANIZATION_SSO_REQUIRED type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 403 type: number title: const: Organization SSO Required type: string type: const: https://photon.codes/docs/problems/organization-sso-required type: string required: - code - status - title - type type: object ResourceMismatchProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: RESOURCE_MISMATCH status: 403 title: Resource Mismatch type: https://photon.codes/docs/problems/resource-mismatch properties: code: const: RESOURCE_MISMATCH type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 403 type: number title: const: Resource Mismatch type: string type: const: https://photon.codes/docs/problems/resource-mismatch type: string required: - code - status - title - type type: object ValidationFailedProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: VALIDATION_FAILED issues: - code: invalid_type location: json message: Expected a string. path: /name status: 422 title: Request Validation Failed type: https://photon.codes/docs/problems/validation-failed properties: code: const: VALIDATION_FAILED type: string detail: minLength: 1 type: string instance: minLength: 1 type: string issues: items: $ref: '#/components/schemas/ValidationIssue' type: array remediation: not: {} requestId: minLength: 1 type: string status: const: 422 type: number title: const: Request Validation Failed type: string type: const: https://photon.codes/docs/problems/validation-failed type: string required: - issues - code - status - title - type type: object ResourceLimitProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: RESOURCE_LIMIT status: 422 title: Developer OTel Query Resource Limit type: https://photon.codes/docs/problems/developer-otel-query-resource-limit properties: code: const: RESOURCE_LIMIT type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 422 type: number title: const: Developer OTel Query Resource Limit type: string type: const: >- https://photon.codes/docs/problems/developer-otel-query-resource-limit type: string required: - code - status - title - type type: object InternalErrorProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: INTERNAL_ERROR status: 500 title: Internal Server Error type: https://photon.codes/docs/problems/internal-error properties: code: const: INTERNAL_ERROR type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 500 type: number title: const: Internal Server Error type: string type: const: https://photon.codes/docs/problems/internal-error type: string required: - code - status - title - type type: object InvalidAuthContextProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: INVALID_AUTH_CONTEXT status: 500 title: Invalid Authentication Context type: https://photon.codes/docs/problems/invalid-auth-context properties: code: const: INVALID_AUTH_CONTEXT type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 500 type: number title: const: Invalid Authentication Context type: string type: const: https://photon.codes/docs/problems/invalid-auth-context type: string required: - code - status - title - type type: object UpstreamFailureProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: UPSTREAM_FAILURE status: 502 title: Upstream Service Failure type: https://photon.codes/docs/problems/upstream-failure properties: code: const: UPSTREAM_FAILURE type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 502 type: number title: const: Upstream Service Failure type: string type: const: https://photon.codes/docs/problems/upstream-failure type: string required: - code - status - title - type type: object ExecutionFailedProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: EXECUTION_FAILED status: 502 title: Developer OTel Query Execution Failed type: >- https://photon.codes/docs/problems/developer-otel-query-execution-failed properties: code: const: EXECUTION_FAILED type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 502 type: number title: const: Developer OTel Query Execution Failed type: string type: const: >- https://photon.codes/docs/problems/developer-otel-query-execution-failed type: string required: - code - status - title - type type: object UpstreamTimeoutProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: UPSTREAM_TIMEOUT status: 504 title: Upstream Service Timeout type: https://photon.codes/docs/problems/upstream-timeout properties: code: const: UPSTREAM_TIMEOUT type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 504 type: number title: const: Upstream Service Timeout type: string type: const: https://photon.codes/docs/problems/upstream-timeout type: string required: - code - status - title - type type: object RequestTimeoutProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: REQUEST_TIMEOUT status: 504 title: Request Timeout type: https://photon.codes/docs/problems/request-timeout properties: code: const: REQUEST_TIMEOUT type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 504 type: number title: const: Request Timeout type: string type: const: https://photon.codes/docs/problems/request-timeout type: string required: - code - status - title - type type: object TimeoutProblem: additionalProperties: $ref: '#/components/schemas/JsonValue' example: code: TIMEOUT status: 504 title: Developer OTel Query Timeout type: https://photon.codes/docs/problems/developer-otel-query-timeout properties: code: const: TIMEOUT type: string detail: minLength: 1 type: string instance: minLength: 1 type: string remediation: not: {} requestId: minLength: 1 type: string status: const: 504 type: number title: const: Developer OTel Query Timeout type: string type: const: https://photon.codes/docs/problems/developer-otel-query-timeout type: string required: - code - status - title - type type: object OtlpAnyValue: anyOf: - additionalProperties: false properties: stringValue: type: string required: - stringValue type: object - additionalProperties: false properties: boolValue: type: boolean required: - boolValue type: object - additionalProperties: false properties: intValue: pattern: ^-?[0-9]+$ type: string required: - intValue type: object - additionalProperties: false properties: doubleValue: anyOf: - type: number - enum: - NaN - Infinity - '-Infinity' type: string required: - doubleValue type: object - additionalProperties: false properties: arrayValue: additionalProperties: false properties: values: items: $ref: '#/components/schemas/OtlpAnyValue' type: array required: - values type: object required: - arrayValue type: object - additionalProperties: false properties: kvlistValue: additionalProperties: false properties: values: items: $ref: '#/components/schemas/OtlpKeyValue' type: array required: - values type: object required: - kvlistValue type: object - additionalProperties: false properties: bytesValue: type: string required: - bytesValue type: object - additionalProperties: false properties: {} type: object ValidationIssue: additionalProperties: false properties: code: minLength: 1 type: string location: $ref: '#/components/schemas/ValidationLocation' message: minLength: 1 type: string path: type: string required: - code - location - message - path type: object ValidationLocation: enum: - body - cookie - form - header - json - param - query type: string headers: Deprecation: description: >- RFC 9745 structured-field Date at which the operation was or will be deprecated: `@` followed by Unix seconds, for example `@1767225599`. schema: pattern: ^@-?[0-9]+$ type: string Idempotent-Replayed: description: True when this response was replayed from an earlier attempt. schema: type: boolean Link: description: Links related to lifecycle or remediation documentation. schema: type: string RateLimit: description: Current rate-limit state. schema: type: string RateLimit-Policy: description: Rate-limit policy applied by the gateway. schema: type: string Retry-After: description: Delay before retrying, in seconds or as an HTTP date. schema: type: string Sunset: description: >- RFC 8594 HTTP-date (IMF-fixdate) after which the operation may become unavailable, for example `Thu, 31 Dec 2026 23:59:59 GMT`. schema: pattern: >- ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$ type: string X-Request-ID: description: Identifier for this HTTP attempt. schema: type: string X-Trace-ID: description: >- Trace ID of this request. Sent alongside X-Request-ID when a middleware published a trace ID for the request. schema: pattern: ^(?!0{32}$)[0-9a-f]{32}$ type: string securitySchemes: accountServiceKey: description: >- Account Service Key, prefixed with `pho_ask_`, sent as `Authorization: Bearer `. Acts on behalf of its owning account, subject to the permissions and credential restrictions of each operation. Account access tokens and OAuth grants also use the Bearer header. In organizations that require SSO, Account Service Keys are not accepted for managing the organization's SSO settings, deleting the organization, or checking whether it can be deleted. scheme: bearer type: http projectApiKey: description: >- Project API key, `pho_sk_` prefixed, sent as `Authorization: Bearer `. Bound to one project, so it is accepted only under `/v1/projects/{projectId}` and refused everywhere else. scheme: bearer type: http oauth2: description: >- OAuth grant issued by the Photon authorization server. The token is a bearer JWT whose consented scope is intersected with the permissions the route grants; an empty intersection is `403 insufficient_scope`. flows: authorizationCode: authorizationUrl: https://auth.photon.codes/oauth2/authorize scopes: account:create_project: Create a project owned by the account. account:read: View account profile. account:read_projects: >- List projects associated with the account; does not grant access to project contents. account:write: Update account name and profile. billing:read: View invoices, usage, payment status. calls:read: >- Read project call data and lifecycle events via supported APIs or approved subscriptions; excludes stored Events queries. events:read: >- Query stored Events and discover their SQL schema within a project. messages:read: >- Read project messages, delivery status, participant changes and typing activity via supported APIs or approved subscriptions. organization:create_project: Create a project in the organization. organization:read: View organization name and avatar. organization:read_projects: List projects in the organization. platforms:read: View project platform configuration. platforms:write: Change project platform configuration. project:delete: Permanently delete the project. project:read: View non-sensitive project settings. project:read_usage: View project usage and costs. project:write: >- Change agent profiles, webhook settings, and other project configuration. ten_dlc:read: View organization 10DLC Brand and Campaign registration records. ten_dlc:write: >- Register and update organization 10DLC Brands and Campaigns, including OTP operations. tokenUrl: https://auth.photon.codes/oauth2/token type: oauth2 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.