> ## Documentation Index
> Fetch the complete documentation index at: https://edgeful.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# run custom report

> run a saved custom report's frozen code, on its saved inputs or another ticker, session or date range; market and granularity stay locked. no AI credits; an uncached run uses your run allowance and a run slot. a result already computed for the same inputs and completed data comes back at once with 200 and every row. otherwise the run starts and answers 202 with status running and its run_id: read it with get custom report run after poll_after_seconds. requires the key's write permission.



## OpenAPI

````yaml /openapi-public.json post /v1/custom-reports/{definition_id}/runs
openapi: 3.1.0
info:
  title: Edgeful API
  description: >-
    Public API reference for Edgeful market analysis. The bearer token is your
    Edgeful API key. Reports support the docs playground. Report responses
    include row-level output in `detailed` only when your plan includes
    row-level detail.
  version: 1.0.0
servers:
  - url: https://api.edgeful.com
    description: Production
security:
  - BearerAuth: []
tags:
  - name: reports
  - name: discovery
  - name: live data
  - name: settings
  - name: custom reports
paths:
  /v1/custom-reports/{definition_id}/runs:
    post:
      tags:
        - custom reports
      summary: run custom report
      description: >-
        run a saved custom report's frozen code, on its saved inputs or another
        ticker, session or date range; market and granularity stay locked. no AI
        credits; an uncached run uses your run allowance and a run slot. a
        result already computed for the same inputs and completed data comes
        back at once with 200 and every row. otherwise the run starts and
        answers 202 with status running and its run_id: read it with get custom
        report run after poll_after_seconds. requires the key's write
        permission.
      operationId: run_custom_report
      parameters:
        - name: definition_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: the saved custom report's id, from the list.
            title: Definition Id
          description: the saved custom report's id, from the list.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomReportRunRequest'
              default: {}
            examples:
              default:
                summary: run on NQ over the last year
                value:
                  controls:
                    ticker: NQ
                    start_date: '2025-10-01'
                    end_date: '2026-09-30'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomReportRunResult'
        '202':
          description: the run started; read it by run_id after poll_after_seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomReportRunResult'
        '403':
          description: >-
            Valid API key, but the account has no API-enabled subscription or
            the key's writes are off.
          content:
            application/json:
              examples:
                missing_entitlement:
                  summary: missing entitlement
                  value:
                    detail:
                      detail: No active subscription with API access found.
                      code: missing_entitlement
                writes_disabled:
                  summary: writes disabled
                  value:
                    detail:
                      detail: >-
                        Enable writes for this API key or connected Claude in
                        the API dashboard.
                      code: writes_disabled
        '404':
          description: No saved custom report with that id belongs to this account.
          content:
            application/json:
              examples:
                not_found:
                  summary: not found
                  value:
                    detail: Custom report not found.
        '409':
          description: >-
            the report needs a rebuild in Edgeful (`detail.code` needs_rebuild),
            or no completed session data covers the requested dates
            (no_completed_data).
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            The account's custom report run write budget is exhausted; wait
            `Retry-After` seconds. Refused attempts count too.
          content:
            application/json:
              examples:
                write_budget_exhausted:
                  summary: write budget exhausted
                  value:
                    detail:
                      detail: >-
                        Custom report run write limit reached. Try again
                        shortly.
                      code: write_budget_exhausted
          headers:
            Retry-After:
              description: seconds to wait before sending the write again.
              schema:
                type: integer
        '503':
          description: The write budget could not be checked; retry shortly.
          content:
            application/json:
              examples:
                write_limits_unavailable:
                  summary: write limits unavailable
                  value:
                    detail:
                      detail: >-
                        Custom report run write limits are temporarily
                        unavailable. Try again shortly.
                      code: write_limits_unavailable
      security:
        - BearerAuth: []
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request POST \
              --url 'https://api.edgeful.com/v1/custom-reports/<definition_id>/runs' \
              --header 'Authorization: Bearer <api-key>' \
              --header 'Content-Type: application/json' \
              --data '{"controls": {"ticker": "NQ", "start_date": "2025-10-01", "end_date": "2026-09-30"}}'
        - lang: python
          label: Python
          source: >-
            import requests


            url =
            "https://api.edgeful.com/v1/custom-reports/<definition_id>/runs"

            headers = {"Authorization": "Bearer <api-key>"}

            payload = {'controls': {'ticker': 'NQ', 'start_date': '2025-10-01',
            'end_date': '2026-09-30'}}


            response = requests.post(url, headers=headers, json=payload)

            print(response.json())
        - lang: javascript
          label: JavaScript
          source: >-
            const url =
            "https://api.edgeful.com/v1/custom-reports/<definition_id>/runs";

            const options = {
              method: "POST",
              headers: { Authorization: "Bearer <api-key>", "Content-Type": "application/json" },
              body: JSON.stringify({"controls": {"ticker": "NQ", "start_date": "2025-10-01", "end_date": "2026-09-30"}}),
            };


            const response = await fetch(url, options);

            const data = await response.json();

            console.log(data);
        - lang: php
          label: PHP
          source: >-
            <?php

            $ch =
            curl_init("https://api.edgeful.com/v1/custom-reports/<definition_id>/runs");

            curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");

            curl_setopt($ch, CURLOPT_HTTPHEADER, ["Authorization: Bearer
            <api-key>", "Content-Type: application/json"]);

            curl_setopt($ch, CURLOPT_POSTFIELDS, '{"controls": {"ticker": "NQ",
            "start_date": "2025-10-01", "end_date": "2026-09-30"}}');

            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

            $response = curl_exec($ch);

            curl_close($ch);

            echo $response;
        - lang: go
          label: Go
          source: |-
            package main

            import (
                "fmt"
                "io"
                "net/http"
                "strings"
            )

            func main() {
                req, _ := http.NewRequest("POST", "https://api.edgeful.com/v1/custom-reports/<definition_id>/runs", strings.NewReader(`{"controls": {"ticker": "NQ", "start_date": "2025-10-01", "end_date": "2026-09-30"}}`))
                req.Header.Set("Authorization", "Bearer <api-key>")
                req.Header.Set("Content-Type", "application/json")
                resp, _ := http.DefaultClient.Do(req)
                defer resp.Body.Close()
                body, _ := io.ReadAll(resp.Body)
                fmt.Println(string(body))
            }
        - lang: java
          label: Java
          source: >-
            import java.net.URI;

            import java.net.http.HttpClient;

            import java.net.http.HttpRequest;

            import java.net.http.HttpResponse;


            HttpClient client = HttpClient.newHttpClient();

            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.edgeful.com/v1/custom-reports/<definition_id>/runs"))
                .header("Authorization", "Bearer <api-key>")
                .header("Content-Type", "application/json")
                .method("POST", HttpRequest.BodyPublishers.ofString("{\"controls\": {\"ticker\": \"NQ\", \"start_date\": \"2025-10-01\", \"end_date\": \"2026-09-30\"}}"))
                .build();
            HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString());

            System.out.println(response.body());
        - lang: ruby
          label: Ruby
          source: >-
            require "net/http"

            require "uri"


            uri =
            URI("https://api.edgeful.com/v1/custom-reports/<definition_id>/runs")

            request = Net::HTTP::Post.new(uri)

            request["Authorization"] = "Bearer <api-key>"

            request["Content-Type"] = "application/json"

            request.body = '{"controls": {"ticker": "NQ", "start_date":
            "2025-10-01", "end_date": "2026-09-30"}}'


            response = Net::HTTP.start(uri.hostname, uri.port, use_ssl:
            uri.scheme == "https") do |http|
              http.request(request)
            end

            puts response.body
components:
  schemas:
    CustomReportRunRequest:
      properties:
        controls:
          anyOf:
            - $ref: '#/components/schemas/ReportControls'
            - type: 'null'
          description: the inputs to change; omit to run the saved inputs.
        retry_of_run_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Retry Of Run Id
          description: >-
            retry a retryable failed run: its run id, sent with the same
            controls.
      additionalProperties: false
      type: object
      title: CustomReportRunRequest
    CustomReportRunResult:
      properties:
        status:
          type: string
          title: Status
          description: >-
            running, the run's outcome such as succeeded or failed, or no_result
            when the report has no successful run.
        definition_id:
          type: string
          title: Definition Id
          description: saved custom report id.
        run_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Run Id
          description: the run that produced the result.
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: a note about the run.
        effective_controls:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: the inputs the run actually used.
        data_through:
          anyOf:
            - type: string
            - type: 'null'
          title: Data Through
          description: the last date the data covers.
        computed_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Computed At
          description: when the run finished.
        retryable:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Retryable
          description: whether a failed run may be retried.
        retry_after_seconds:
          anyOf:
            - type: integer
            - type: 'null'
          title: Retry After Seconds
          description: seconds to wait before retrying.
        poll_after_seconds:
          anyOf:
            - type: number
            - type: 'null'
          title: Poll After Seconds
          description: 'while running: seconds to wait before reading the run again.'
        route_to_refine:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: where to refine the report.
        summary:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: the result's summary values.
        detailed_data:
          anyOf:
            - items:
                $ref: '#/components/schemas/JsonValue'
              type: array
            - type: 'null'
          title: Detailed Data
          description: the result's rows, every one the run stored.
        total_rows:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Rows
          description: rows in the result.
        truncated:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Truncated
          description: true when the response does not carry every row.
        column_units:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: units per column.
        row_label:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: what a row represents.
        row_grain:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: the row grain.
        presentation:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          description: presentation hints.
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: the report in Edgeful.
      additionalProperties: true
      type: object
      required:
        - status
        - definition_id
      title: CustomReportRunResult
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ReportControls:
      properties:
        ticker:
          anyOf:
            - type: string
              maxLength: 30
              minLength: 1
            - type: 'null'
          title: Ticker
          description: the ticker to run on, within the report's market.
        market_type:
          anyOf:
            - type: string
              enum:
                - futures
                - stock
                - forex
                - crypto
            - type: 'null'
          title: Market Type
          description: the report's market; any other market is refused.
        session:
          anyOf:
            - type: string
              maxLength: 80
              minLength: 1
            - $ref: '#/components/schemas/ReportSession'
            - type: 'null'
          title: Session
          description: a standard session name, or a custom window.
        start_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Start Date
          description: first date of the window, YYYY-MM-DD.
        end_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: End Date
          description: >-
            last date of the window, YYYY-MM-DD; runs stop at the last completed
            session.
      additionalProperties: false
      type: object
      title: ReportControls
      description: >-
        Inputs a custom report run may change; the report's market and
        granularity stay locked.
    JsonValue: {}
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ReportSession:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 80
              minLength: 1
            - type: 'null'
          title: Name
          description: a label for the window.
        start_time:
          type: string
          pattern: ^\d{2}:\d{2}(:\d{2})?$
          title: Start Time
          description: start of the window as HH:MM or HH:MM:SS in the timezone.
        end_time:
          type: string
          pattern: ^\d{2}:\d{2}(:\d{2})?$
          title: End Time
          description: end of the window as HH:MM or HH:MM:SS in the timezone.
        timezone:
          type: string
          maxLength: 80
          minLength: 1
          title: Timezone
          description: IANA timezone the clocks are read in.
          default: America/New_York
      additionalProperties: false
      type: object
      required:
        - start_time
        - end_time
      title: ReportSession
      description: A custom session window that replaces the report's session for a run.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Send your Edgeful API key in the Authorization header as `Bearer
        <api-key>` (for example, `Bearer ef_live_<random>`).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.